Skip to content

Setup SSH key for local dev box and use agent forwarding for servers

Jump to bottom
Michael Hulse edited this page Jul 18, 2019 · 13 revisions

Attention macOS users

Technical Note TN2449: OpenSSH updates in macOS 10.12.2

Checking for existing SSH keys

$ ls -al ~/.ssh
# Lists the files in your .ssh directory, if they exist

Options:

  1. If you don't have an existing public and private key pair, or don't wish to use any that are available to connect to BitBucket, then generate a new SSH key.
  2. If you see an existing public and private key pair listed (for example id_rsa.pub and id_rsa) that you would like to use to connect to BitBucket, you can add your SSH key to the ssh-agent.

Generate a new SSH key and adding it to the ssh-agent 

$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Follow the on-screen instructions.

Adding your SSH key to the ssh-agent

Start the ssh-agent in the background:

$ eval "$(ssh-agent -s)"
# Windows users, no quotes:
# $ eval $(ssh-agent -s)

On a macOS, edit ~/.ssh/config and add this:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_rsa

Add your SSH private key to the ssh-agent and store your passphrase in the keychain:

$ ssh-add ~/.ssh/id_rsa
# macOS users, store your passphrase in the keychain using:
# $ ssh-add -K ~/.ssh/id_rsa

Note: REVERSING the above process is easy:

# Remove a specific identity:
$ ssh-add -d ~/.ssh/id_rsa
# Remove all identities (i.e. cached keys):
$ ssh-add -D
$ rm ~/.ssh/id_rsa*

Check your saved keys:

$ ssh-add -l

Copy SSH key

Copy your key to your clipboard:

$ cat ~/.ssh/id_rsa.pub | pbcopy

Or, if you don’t have pbcopy, just cat the file and copy the output manually.

Setting up SSH agent forwarding

Confirm that your own SSH key is set up and working:

# GitHub:
$ ssh -T git@github.com
# Bitbucket:
$ ssh -T git@bitbucket.com

Open or create ~/.ssh/config.

Add this:

Host example.com
  ForwardAgent yes

Replace example.com with your domain or its IP address.

You can check that your key is visible to ssh-agent by running the following command:

$ ssh-add -L

If the command says that no identity is available, you'll need to add your key:

$ ssh-add ~/.ssh/id_rsa
# On macOS, import your SSH keys into the Keychain:
# $ ssh-add -K ~/.ssh/id_rsa

Note, on Linux, you will need to add this to your profile:

eval `ssh-agent`
ssh-add -k

Reload your profile:

$ source ~/.bash_profile

Now you can SSH into the desired server and your SSH key will allow you to pull/push without having to setup a key on the server.

Add key to BitBucket

  1. On BitBucket, choose avatar > Manage Account.
  2. Switch to the account you want to manage and click SSH keys; add a new key which should be named to match the server name (e.g., dev.foodomain.com).
  3. Paste the key into the Key field and click Add key.

Example config

Note: UseKeychain is for macOS.

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_rsa

Host 172.17.*
  ForwardAgent yes

Host 10.1.10.*
  ForwardAgent yes

Copying existing

You can also copy an existing id_rsa private key to a server; as long as the id_rsa.pub public key matches (via Bitbucket or GitHub), and you’ve added the key to the ssh-agent (and reload your profile) then everything should work. Though, I do suggest you take the time to setup ssh agent forwarding.

Troubleshooting

  • If you have ssh agent forwarding setup properly on you Mac, but it’s not working on the connected server, you may need to disconnect from the server, and then run ssh-add -K on your Mac. The next time you connect to the server, it should work.

Links

Clone this wiki locally