The problem#

SSH public key authenication can make SSH much more convenient because you do not need to type a password for every SSH connect. Instead, in common usage, the first time you connect, GNOME Keyring, KWallet, or your desktop environment's equivalent will pop up and offer to keep your decrypted private key securely in memory. Those programs will remember your key until the next time you reboot your computer (or possibly until you log out completely and log back in).

But those are tied to your desktop environment. If you are not at a GUI, either using a computer in text-mode using a console or connecting over SSH, then you do not have access to those programs.

Introducing ssh-agent#

Both of those programs are emulating the features of ssh-agent, and we can get more control by using that program directly. ssh-agent is a somewhat weird program to use since running just leaves it running in the background after it prints out some shell commands:

$ ssh-agent 
SSH_AUTH_SOCK=/tmp/ssh-iC8azplzRAjD/agent.25886; export SSH_AUTH_SOCK;
SSH_AGENT_PID=25887; export SSH_AGENT_PID;
echo Agent pid 25887;

To actually use it you can either run eval $(ssh-agent) to run that shell code it outputs in the current shell or ssh-agent bash to have it start a new shell with those environmental variables set. Then ssh will see the SSH_AUTH_SOCK and SSH_AGENT_PID variables and use that information to communicate with the ssh-agent process now running in the background.

Once ssh-agent is properly configured, ssh-add can be used to load keys. Usually the argument isn't needed as you probably only have one key on your computer placed in the default location when you generated it with ssh-keygen. If not, you can specify the private key file as an argument to ssh-add.

Same agent, many logins#

The environmental variables for ssh-agent are only around in the shell it was originally run in and its children. This could be the first thing run on login, but with SSH, it's quite possibly to have many logins to the same computer. It would be nice to be able to share an agent.

There are some solutions online, but the one I use is a script I got from my friend Trevor Caira called ssh-reclaim. To use it, download ssh-reclaim, save it as ~/bin/ssh-reclaim, and add the following to your ~/.bash_profile to run it on every login:

if [ -f bin/ssh-reclaim ]; then
    . bin/ssh-reclaim
fi

Because ssh-reclaim sets environmental variables, it has to be sourced with ., so it will run in the current context instead of a subshell.

The script works by storing the agent's socket in ~/.ssh/ (tagged with the hostname so it works with home directories shared by multiple hosts) and uses it to reconnect to the ssh-agent process. If it can't find one it can connect to, then it deletes any old sockets and kills any ssh-agent processes it can't connect to before starting a new one.

Agent forwarding#

If you find yourself often SSHing into a computer and from there SSHing into another computer, SSH agent forwarding may better suit your needs. That allows a computer you connect to over SSH to use the ssh-agent of the computer you are connecting from.

For details on what's going on with public key authenication and SSH agent forwarding, this page explains it in detail with diagrams.