SSH Tutorial

Aaron Bauer

December 27, 2021

Remote Access with SSH

SSH, the Secure Shell, supports remote login and command-line or GUI access across the network through encrypted tunnels protected by public-key cryptography.

SSH is a useful tool that allows doing all your work in your CS account, even while working outside the GNU/Linux lab, including from any campus Mac computer or, in some cases, your personal computer. Using SSH has some limitations and caveats that require occasional care and attention to avoid.

SSH Availability


The host machine is the machine to which you want to connect, in this case, a CS machine where you will do your work. All CS GNU/Linux workstations support incoming and outgoing SSH access.


The client machine is the machine that you are physically using to connect to the host.

The GNU/Linux and macOS environments include a built-in SSH client. On Windows, you can use the standard SSH client in the Windows Subsystem for Linux (WSL) (a mostly-sort-of-GNU/Linux environment hosted inside the Windows operating system) or install a Windows-native SSH client like PuTTy.

SSH via VS Code

Make sure to follow these steps carefully—doing one incorrectly may prevent SSH from working in VS Code.

  1. Install VS Code for your client machine (e.g., install it on your laptop)
  2. Install the Remote - SSH extension in VS Code (via the link, or by going to View > Extensions, eand searching for ssh)
  3. Use F1 to bring up command palette (or Ctrl/Cmd-Shift-P), type in “ssh” and select “Remote-SSH: Connect to Host…”
  4. Select “Add New SSH Host…” and then enter ssh as the ssh command (replacing YOUR_CARLETON_USERNAME with the part of your Carleton email before the @)
  5. If prompted, select the first option for which config file you want to modify
  6. Click “Connect” on the dialog that pops up in the lower right (or go to the Remote Explorer tab along the left side, and then right click on mantis and connect in current window)
  7. If prompted, select “Linux” for the platform of the remote host
  8. If prompted about a “fingerprint”, select “continue”
  9. Enter your Carleton password when prompted
  10. Then View > Explorer, select Open Folder to have VS Code open the folder where you want to work

If you can’t connect after following these steps, use F1 to bring up the command palette, type in “ssh config” and select “Remote-SSH: Open SSH Configuration File…”. Choose the same one you selected in step 5 (should be the first option). Make sure you see an entry that looks like this:

  User awb

If you see one containing mantis that doesn’t look like that, delete it, and try again starting from step 3.

Basic Command-Line SSH Usage


  1. You are logged into a campus Mac or you are on campus using a laptop with internet access and an SSH client installed. Let’s call that machine client.
  2. You wish to work on the CS lab workstation whose host name is On the campus network, “inside” the domain, you can leave off “”.
  3. Your Carleton username is ccarleton.

In the example below, a line prefix up through the $ symbol indicates the command prompt. Text to its right on the same line is the command. Lines not starting with this prefix are output from commands.

On your client machine, open a terminal and use the following ssh client command to log in to the machine mantis as user ccarleton and establish a remote command-line shell on mantis:

carl@client:~$ ssh ccarleton@mantis

On your first login from your client machine, SSH will prompt for confirmation.

On all logins, enter your Carleton password when SSH prompts for it:
ccarleton@mantis's password:

Once you enter your Carleton password successfully, SSH will present you with a shell running on mantis, as if you had logged in physically and opened a terminal on mantis.

Notice that the prompt shows that your shell is running on mantis, indicated by @mantis. This prompt helps tell whether you are running commands on your machine or the remote machine.


Any commands you enter here run on mantis, manipulating files on mantis, etc., but the interactive input/output happens here in this terminal on your client machine instead of on mantis‘s’ screen and keyboard.

When you are done working on mantis log out by typing logout, exit, or Control-D at the command prompt. SSH will close the connection and exit, returning you to the command prompt on your local machine.

ccarleton@mantis:~$ logout
Connection to mantis closed.

First login

SSH always checks that the remote machine is who you think it is. The first time you connect to any given host from here, your local SSH client has no way of knowing if this is the same machine as last time, since there was no last time.

The authenticity of host ' (' can't be established.
RSA key fingerprint is SHA256:VV6Y83C2KcoUuyZEUYRcO/G/sDWnJ/gQRav88uGoXxE
Are you sure you want to continue connecting (yes/no)?

Enter yes at the prompt to continue.

SSH will remember this fingerprint and check it again every time you connect to mantis in the future, aborting if it does not match.

Warning: Permanently added ', (RSA) to the list of known hosts.


Be aware the remote work comes with some caveats that require you to more mindful of your work than when you work directly on a physical machine.

Dropped SSH Connections

If you close your laptop, if the WiFi drops out, or if your client machine otherwise loses network access, the SSH connection will be broken, and any in-progress remote commands will terminate in error. This includes unfortunate results like losing your last few minutes (or more) of work. Save often, definitely before closing or moving your laptop! A dropped SSH connection can also mean losing your context if you had many shells or editor windows open. Unfortunately, this can happen more often than desirable due to sometimes spotty WiFi coverage.

Concurrent SSH Login and Local Login

If you log in to a workstation physically and also login as the same user remotely, you may experience odd effects when trying to start potential GUI applications like emacs. Even though your command-line SSH connection may not support GUI access, emacs might happily pop up on the GUI on the screen where your are logged in physically. This is pretty annoying if you are not actually in the lab, but forgot to logout before leaving this workstation. Log out when you leave.

Remote Graphical User Interface (GUI) Access over SSH

By default, SSH opens connections that support only text command-line interaction. The -X option of the ssh client allows individual windows from the host’s window system (called X) to be piped across the network to your local client machine as well. Depending on your client machine operating system, you may need extra software on the client (your client machine) to display the GUI:

As before, you get a command-line shell running on mantis, but now, any GUI application that you launch from the shell (e.g., emacs) will run on mantis as before, but will show its windows here on your local display.

GUI Caveats

In addition to the standard caveats about remote SSH work, you should take care interacting with remote GUI applications.

Public Key Authentication and Advanced SSH Usage

Password authentication works fine for SSH, but can get tedious if you use SSH frequently, although using a password manager or keychain on your client machine may help. Password authentication is also susceptible to all the issues around passwords. Public key authentication is an attractive alternative.

Several SSH features, like the SSH agent, host aliases, etc., make using SSH more efficient, robust, or secure. They generally require some learning and configuration work.

We do not have time to write about public key authentication or other features now, but feel free to ask. A quick web search for “ssh key” will yield many helpful resources.