Skip to end of metadata
Go to start of metadata

Storing Your Keys: SSH-Agent, Agent Forwarding, and Keychain

While the previous steps accomplish the task of allowing for key based ssh authentication, it is inconvenient to type your passphrase every time you log in or transfer files. We've already seen that PuTTY has a built in mechanism for storing keys for you. MacOSX also has a keychain that can store your ssh key.  Similarly, OpenSSH has the very convenient capability ofusing an "SSH Agent" program, whose purpose is to temporarily store the private keys that you've previously unlocked by entering your passphrase.
This functionality is handled by a variety of different programs, depending on the OS involved, and even the set of desktop applications. Here we'll provide a quick tutorial on using OpenSSH's built in "ssh-agent" program, and a list of links to other, often more convenient programs. In addition we'll talk about the "keychain" set of scripts.

Lastly, we note that many modern Linux Desktop suites startup and manage ssh-agent for you, providing a convenient GUI for adding keys, and that Mac OS X 10.5 now integrates ssh-agent into its GUI.


ssh-agent is a daemon that runs in the background, and stores decrypted privates keys in memory for you; it is part of OpenSSH. Keys are added to it using the "ssh-add" command; when you attempt to access a remote using ssh, scp, or sftp, these programs look for the ssh-agent, and attempt to read all the known keys before querying you for passphrases or passwords; thus once a key is added to your ssh-agent, you want have to type the passphrase again while that agent is running and accessible.

To use ssh-agent, invoke it as you start a new shell:

or in a currently running shell

(this is for a Bourne shell or similar; use "-c" when running in a c-shell).

This will start up an shh-agent process, and set certain environment variables (in particular $SSH_AUTH_SOCK) to let other programs know how to communicate with ssh-agent.

Once started, you can add keys to the agent using the ssh-add command; when first run, it will automatically try to load the keys /.ssh/id_rsa, /.ssh/id_dsa and ~/.ssh/identity if they exist, and will ask for their passphrases:

You can add more keys by including the the filename on the command line:

You can then list available keys with the "-l" option, and delete with the "-d" option

Now when you use ssh, sftp, or scp, your decrypted private keys are available from the agent, and the command with execute without the need to enter password or passphrase.

Once problem with ssh-agent, is that you can end up with many ssh-agent processes running in the client computer, when all you really need is a single ssh-agent to handle all your keys. External programs are available to remedy this situation.


The "keychain" set of scripts manages thessh-agent processes so that you only start a singlessh-agent process for all your running shells. For most scenarios it's usually easiest to install it locally to your home directory.
Install the keychain script into your home directory (something like ~/bin/keychain). You can download it from here , (this site is presently not up, but a local cache of the script is available here\ .)

For example:

Once installed, you'll need to modify your login script to run keychain: For BASH, add the following to you ~/.bash_profile

In your shell init script, add lines to set up the environment vars needed to access ssh-agent. For example, in your ~/.bashrc, add the following lines:

Then when you log in, you'll invoke keychain as follows:

When you start the next shell, ssh-agent will be available immediately without any further commands.

The man page for keychain is available here.

Agent Forwarding

Agent forwarding allows the keys stored in your ssh-agent on the client to "forwarded" to all ssh invocation on the remote machine; it's as if you started ssh-agent on the remote machine as soon as you logged in, and thus can ssh from the remote server to another similar without the need to enter a password:

And on and on. To enable agent forwarding, add the "-A" option when you run ssh, or add the line "ForwardAgent yes" to the ssh config file, ~/.ssh/config.

Programs For Storing ssh Keys

Linux and Unix (and CygWin on Windows):
  • OpenSSH's ssh-agent
  • keychain: a set of scripts to manage ssh-agent (install into your home directory)

Most Windows clients will manage this themselves, and so an external program is not relevant.

  • None