How to SSH

SSH, or Secure SHell, is a program used to securely login to a remote computer. As of this writing, the ssh command is builtin to Windows, MacOS, and Linux, so you do not need to install any third-party software to use it. However, if you are using Windows, I suggest using a dedicated terminal emulator such as Windows Terminal or Git Bash instead of the old batch command prompt window, which does not handle all ANSI escape sequences properly.

Password-based authentication

See Machine List for a list of general-use machines which you may SSH into. Let's say your CSC username is ctdalek and you want to use the corn-syrup machine. Then run the following command from your terminal:

ssh ctdalek@corn-syrup.csclub.uwaterloo.ca

Then enter your password. If this is your first time, check the email you received from CSC when you signed up; it should contain a temporary password in it.

If you are off-campus, you will also be prompted for a 2FA code via DUO (see Two-Factor Authentication for details). Since this is annoying, I suggest setting up public key-based authentication instead (see below).

Public key-based authentication

Pubkey auth is far more convenient since you do not have to enter your password every time. If you are a CS student, chances are that you may already have created an SSH key for one of your courses; if not, just run the command ssh-keygen and follow the prompts.

The ssh-keygen command will create two files: a private key and a public key, by default named id_rsa and id_rsa.pub. (If you chose ED25519 as your signature algorithm, these will be named id_ed25519 and id_ed25519.pub instead). You will want to get the content of the public key file.

On MacOS, Linux, Git Bash and PowerShell, run the following command to print the file's content:

cat ~/.ssh/id_rsa.pub

If you are using the old Windows command prompt, run the following instead:

type %USERPROFILE%\.ssh\id_rsa.pub

Copy the output to your clipboard. It will look something like this (example only):

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCzaWV...hNUzpnsbVsHGZy7k= ctdalek@desktop-pc

Note that the last part (in this case, "ctdalek@desktop-pc") is just a comment - you can actually put anything you want there.

Now SSH into a CSC machine. If you do not have a .ssh directory yet in your home directory, create it now:

mkdir ~/.ssh

Now open the file ~/.ssh/authorized_keys. In this example we will use the nano text editor, but any editor will do.

nano ~/.ssh/authorized_keys

Paste your public key into this file. Once you are done, save and close the file (if you are using nano, run Ctrl-O, Enter, Ctrl-X).

Now whenever you run the SSH command from your computer, you won't need to enter a password anymore.

ssh_config

SSH has a lot of different configuration options which can be placed in the file ~/.ssh/config (on your local computer, not the remote). See https://linux.die.net/man/5/ssh_config for a reference. Here's a basic config file:

Host csc
    HostName corn-syrup.csclub.uwaterloo.ca
    User ctdalek

Now whenever you run ssh csc from your terminal, you will login to corn-syrup.

Forward proxy

Let's say you're running a server program on a CSC machine, and it's running on localhost:3000 on the remote. One way to access this locally is to use a forward proxy:

ssh -L 3000:localhost:3000 ctdalek@corn-syrup.csclub.uwaterloo.ca

Now localhost:3000 on your local machine will be forwarded to localhost:3000 on the remote.

Reverse proxy

Let's say you're running a server program locally listening on localhost:3000, and you want to access this from the remote. In this case, you want to create a reverse proxy:

ssh -R 3000:localhost:3000 ctdalek@corn-syrup.csclub.uwaterloo.ca

Now localhost:3000 on the remote will be forwarded to localhost:3000 on your computer.

SOCKS proxy

This is useful for when you want to proxy all of the traffic for a particular application through a remote. This requires SOCKS support from the application. Firefox is one such application, which is useful if you want to visit a website which can only be accessed from an on-campus IP address. Run the following first (you can choose a different port if you want):

ssh -D 8132 ctdalek@corn-syrup.csclub.uwaterloo.ca

Now in Firefox, go to the URL about:preferences, scroll to the bottom, click on the Settings button, choose "Manual proxy configuration", set SOCKS Host to localhost, and set the port to 8132. Also choose "SOCKS v5" and check the "Proxy DNS when using SOCKS v5" option. Now click OK. All of Firefox's network connections should now be proxied through the remote machine.