Generate a key pair

We will be using a special git repository set up on ece2524.ece.vt.edu to submit homeworks and projects. The server requires SSH key authentication, to use it first check for existing key files:

$ ls ~/.ssh/

Check if there is a file named either id_rsa.pub. If there is, you have already created a key. If you want to use this key then skip to Install Your Key. If you don’t have key, or want to create a new one continue with:

$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/you/.ssh/id_rsa):

Just press <ENTER> to accept the default file location unless you know what you are doing and want to use a different file name.

Now enter a passphrase

Enter passphrase (empty for no passphrase): [Type a passphrase]
Enter same passphrase again: [Type passphrase again]

Your identification has been saved in /home/you/.ssh/id_rsa.
Your public key has been saved in /home/you/.ssh/id_rsa.pub.
The key fingerprint is:
01:0f:f4:3b:ca:85:d6:17:a1:7d:f0:68:9d:f0:a2:db user@host

Notes:

• Only run this command once. If you run it again and generate a new key in place of the old one any authentication you have set up will no longer work.
• using an empty password: generating a key pair with no password is a potential security risk. The security obtained by public key authentication is only as good as how secure your private key is. If an unathorized person gains access to your machine, either locally, or remotely, they can obtain your private key. If there is no password set on it the hacker will immediately have access to all servers that you have installed the public key to. If you only use this particular key pair to access your ECE2524 git account then worst case scenario is this person will be able to submit homework assignments for you (or tamper with them). Not a huge deal. If you also use the same key pair to authenticate your CVL account, or any other system with full shell access this is a much greater threat. Consider setting a passphrase when generating your key!
• creating a keypair on your CVL shell account: For the reasons given above, storing your private key on a shared system connected to the internet is less secure than storing your key on your own computer. If the only Unix-like system you have access to is your CVL shell account, then you don’t have any other option. If, however, you run a Unix-like system on your own computer (e.g. Linux, OpenBSD, OS X) you should create your key pair locally and then use SSH Agent Forwarding to authenticate to remote servers when connected to your shell account.

What Just Happened?

After running the ssh-keygen command and supplying the necessary information you will be left with two files in your ~/.ssh directory:

$ ls ~/.ssh
id_rsa   id_rsa.pub

The file id_rsa is your private key. Keep it safe. You should never send your private key across a network. The id_rsa.pub is the public key associated with id_rsa. You will copy id_rsa.pub to remote machines that you have access to to allow passswordless authentication.

Install your key

$ scp ~/.ssh/id_rsa.pub USERNAME@ece2524.ece.vt.edu:/dropbox/USERNAME.pub

Replace USERNAME with your CVL account username.

Note: If your CVL account username is different from your VT PID tell me in an email what it is. The install script running on the server checks that the person trying to install the key is on the class roster which is based on your VT PID. After you get a confirmation from me that I’ve made the necessary adjustment, then run the above command to copy your key to the /dropbox directory on the serever.

Advanced Users: Multiple Keys

If you want to use multiple keys (e.g. you want to be able to access the ece2524 git server from both your desktop and laptop) then use

$ scp ~/.ssh/id_rsa.pub USERNAME@ece2524.ece.vt.edu:/dropbox/USERNAME@MACHINE.pub

where you replace USERNAME with your CVL account username¹ and MACHINE with a word unique to each of your different machiens (e.g. desktop or laptop). I am using gitolite as the git server. See multiple keys per user in the gitolite documentation for more information.

Forward your SSH Agent

Create a file .ssh/config in your home directory and in it write

Host ece2524.ece.vt.edu
    ForwardAgent yes

to it. You can easily do this from the command line by running the following command:

$ echo -e "Host ece2524.ece.vt.edu\n    ForwardAgent yes" >> ~/.ssh/config

Now, if you connect to your shell account using ssh you should still be able to authenticate with the git server. On many distros and environments including Ubuntu with Unity and Fedora with Gnome, this is all you will have to do because these environments automatically start a program called an SSH Agent when you log in. If you add this file, and you find that authenticating with the git server is not working when you connect to your shell account then it could be that an SSH Agent isn’t running for some reason. Stop by office hours and we’ll get it sorted out.

More .ssh/config tricks

We are going to be typing ece2524git@ece2524.ece.vt.edu a lot when we start using git to manage our coding projects. The ece2524git is the user name and ece2524.ece.vt.edu is the host name. We can set these as parameters in our .ssh/config to save some typing:

Host ece2524
    HostName ece2524.ece.vt.edu
    User ece2524git
    ForwardAgent yes

Make sure to set appropriate permissions on the config file or else ssh will complain:

$ chmod 600 ~/.ssh/config

Now wherever you would use ece2524git@ece2524.ece.vt.edu in a git or ssh command you can use ece2524 instead

1. Fork a repo

   ssh ece2524 fork skel/redir USER/redir
       

2. Clone a repo

   git clone ece2524:test
       

3. Connect to your shell account

   ssh your_cvl_username@ece2524
       

To avoid confusion I will continue to use the full url in my examples. Just know that if you created that config file then you can get away with a lot less typing.

Test

If your key was installed successfully you should now have access to the git server. Try running the following command:

$ git clone ece2524git@ece2524.ece.vt.edu:test /tmp/test
Cloning into 'test'...

and then check that there is a new directory named test containing a file called README.

$ cat /tmp/test/README
You have successfully cloned or fetched a repo from the ece2524 git server.
This means your public key was properly installed.

If the git clone command did not work, or there is no /tmp/test/README file after running it, send me an email with an exact copy of the commands you ran and any output they produced.

Footnotes

¹ Strictly speaking you don’t need to use your CVL username as the name of your key file. You could pick any username that is not already in use by gitolite. I find it is generally much less confusing if you just stick with your CVL username unless there is a very good reason not to.