SSH Troubleshooting

EVERYONE READ THIS!

To use SSH in SWEN-344, you need to do the following ONE TIME:

  1. Generate a pair of SSH keys (i.e. run ssh-keygen, get two key files)
  2. Register your key file that ends in .pub with GitLab
  3. Make sure Git knows where to find ssh (i.e. GIT_SSH environment variable)

Then every time you RESTART your computer, you’ll need to:

  1. Cache your SSH key in the SSH agent (i.e. ssh-add)

We’ll go over OS-specific details down below, but the above is the essence of what we’re doing.

What is SSH?

The Secure Shell, or ssh is the de facto cryptosystem for securely connecting two computers. In our setup, we prefer to use SSH because it:

  • Uses mulit-factor authentication without using your phone
  • It’s easy to revoke
  • You don’t have to enter your password over and over again

Git, GitHub, and GitLab all prefer to use SSH when doing a:

  • git push
  • git pull
  • git fetch
  • git remote update ..and others operations over a network.

Windows

Installing SSH

Do I have SSH? In a terminal (could be Command Prompt, could be Powershell - doesn’t matter), type ssh -v. If it says “command not found”, then you need to install OpenSSH.

We recommend following the Windows instructions, particularly the GUI version through Optional Features.

Recent versions of Windows have OpenSSH installed automatically, so this step might not be necessary. Also, many systems (such as Git for Windows) will install SSH for you as well. While handy, this can lead to multiple copies of OpenSSH on your system that can get confusing sometimes.

Generating key pairs

Did this before? You may have done this step in the past but forgot where the keys files were. There’s no harm in regenerating your key files, and we’ll add them to their default location so SSH can find them easily next time.

In a terminal (could be Command Prompt, could be Powershell - doesn’t matter), type ssh-keygen. You’ll get an output that looks something like this:

Generating public/private rsa key pair.
Enter file in which to save the key (c:\Users\YOURUSERNAME\.ssh\id_rsa):

We recommend pressing “ENTER” for this step and going with the default. SSH will look for your keys here next time.

The prompt will then ask you for a passphrase. Set it to a password that you can remember later. We don’t recommend using “no passphrase” - if we set things up properly we won’t need to type in our password very often.

Your output will look something like this:

Your identification has been saved in c:/Users\YOURUSERNAME/.ssh/id_rsa
Your public key has been saved in c:/Users/YOURUSERNAME/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:UQGRchvzplLcICUtrTlOLlxB1pqQAYSiE/uZ+Mt+oJ0 YOURUSERNAME@YOURCOMPUTERNAME
The key's randomart image is:
+---[RSA 3072]----+
| oo..++=++o.     |
|+   o.=.X.       |
|oo   . %.B       |
|+     O +.+      |
| + + = oSo       |
|. = o + .        |
| + o . .         |
|..E .            |
| .+o             |
+----[SHA256]-----+

Note: your SHA26 fingerprint and randomart will look different than mine.

Registering with GitLab

Your GitLab profile needs to know about these keys. You’ll need to copy the contents of your id_rsa.pub key over to the

What about PuTTY?

PuTTY is an older way of accomplishing all this. We prefer OpenSSH to PuTTY because we find it simpler to work with. Also, tools like VS Code don’t work nicely with PuTTY and prefer OpenSSH.

Mac

We recommend doing this in your Terminal.

Instructions not (yet) written. Contributions welcome!

Linux

Instructions not (yet) written. Contributions welcome!

In general, these instructions line up with Mac instructions. Linux tends to have SSH set up properly by default, so we don’t usually