Using SSH Keys in Linux/MacOS

Generating an SSH Key Pair

If you are on a unix-like operating system, chances are you already have SSH installed in some form or another. Typing 'ssh' at the command line should give you a good indication whether or not it is installed. If the 'ssh' command is not recognized by your OS, you will need to install SSH. You may go to http://www.openssh.com/ for more information.

To generate an SSH key pair, here is the command that works on most versions of Unix: 

ssh-keygen -t rsa -b 2048

You will then find your private and public key in the .ssh directory of your home dir. Use the following command to list them: 

ls $HOME/.ssh/

You will find two files with the same base name (usually "id_rsa"), but your public key will have the ".pub" file extension.

You may also generate an SSH key pair using our online key generation tool. Here's how:

  1. Go to http://sshcontrol.com/ssh_keys/generate
  2. Enter a passphrase and click 'Generate'. The passphrase will be used to encrypt your private key and will be needed in establishing an authenticated connection to your SSH Control repositories.
  3. The website will generate a file called 'sshkeys.zip'. Save the file to a location on your computer.
  4. Unzip/extract the sshkeys.zip file.

Extracting the zip file will give you two files, id_rsa and id_rsa.pub, your private and public keys, respectively.

Uploading A Public Key to SSH Control

There are two instances when you will want to upload a public key to SSH Control:

  1. Setting your Profile SSH Key (click the Profile button when you are logged into the Member Portal)
    Add_profile_ssh_key
  2. Adding an SSH Key to a project you created yourself or to which you were invited (click the 'custom key' button in the Project and Assignment pages)
    Add_key_to_project

Uploading a public key is easy, but remember not to confuse it with your private key. Public keys will usually have the file extexsion '.pub' to distinguish it from its associated private key.

Copy and paste the contents of your public key into the form on SSHControl.com when prompted to enter an SSH Public Key. You can do this in the following way:

  1. Use the following command to list the contents of your public key file: 
    cat $HOME/.ssh/id_rsa.pub
  2. Highlight and copy the outputted string (starting with ssh-rsa or ssh-dsa).
  3. In the SSHControl.com form field, paste the string.

When you press the button to save your key, we will let you know if the key you submitted is valid or not.

Using an SSH-Agent

You will soon find typing in your SSH passphrase for every checkin or update can be quite tedious if you interact with your repositories multiple times a day. Using an agent, however, will only require you to type your passphrase once. Here's how you can get started with an SSH agent (assuming you have already gone through the steps of generating an SSH key pair).

  1. Start your agent with the following command: 
    eval `ssh-agent`
  2. Add your key to the agent's key chain 
    ssh-add
    The 'ssh-add' command by itself will try to add the private key located at $HOME/.ssh/id_rsa first, then $HOME/.ssh/id_dsa second. If you want to specify a specific key to be added, simply append the location of your key to the 'ssh-add' command like so 
    ssh-add %HOME/.ssh/another_key_name

After you type in your passphrase for your private key, your agent will automatically try to use that key (and any other keys on its key chain) when trying to establish an SSH connection. That means, next time you issue a 'svn update', 'git pull', 'hg push', or any other command which will communicate with your SSH Control repository, you won't have to type in your passphrase.

You may kill your agent at any time with the following command: 

ssh-agent -k