ssh-agent is a program that can be used in UNIX-like operating systems such as Linux, OpenBSD and Darwin. It's purpose is to manage and facilitate public key authentication for a user's processes throughout their session, hence making secure remote access much simpler and more flexible.

Without ssh-agent

A couple of decades ago, most remote access on UNIX machines was done via the 'r'-generation of tools; rsh, rlogin and rcp. This made life very easy for users - they could seamlessly access computers on the other side of the world without even pausing to enter a password. Unfortunately, it also made things very easy for malicious hackers who could exploit the basic security mechanisms to gain unsanctioned access to other computers.

With the new 's'-generation of tools based around ssh, security was much improved as all network traffic is encrypted. However, ssh brought it's own disadvantages: users were now expected to enter passwords in order to log onto a machine, which raises password management issues, as well as being very inconvenient.

An alternative is to use public-key authentication, where a client validates itself to a server using a "three-way handshake" with a public/private keypair it has created and informed the server about. This means the server doesn't ask for a password, but a passphrase is still required by the client to authorise use of this keypair. Once again, a user has to remember and enter a string every time she wants to make a connection.

With ssh-agent

The advantages

Instead of having to enter a passphrase or password every time a user wants to connect to a machine, using ssh-agent means a passphrase is entered once, when a user logs in. Subsequently, that keypair can be used automagically by any processes started in that session. This means that when I log in, a box pops up saying "Enter passphrase for keypair ...". After I enter that passphrase, I can transperently, and securely, access any server with which I have set up public-key authentication. For example, at a terminal, instead of seeing

jmj@clientPC ~ $ ssh serverPC
Password: ***********
Linux serverPC i686 GNU/Linux
Last login: Tue Oct 19 13:38:27 2004 from clientPC
I just see
jmj@clientPC ~ $ ssh serverPC
Linux serverPC i686 GNU/Linux
Last login: Tue Oct 19 13:38:27 2004 from clientPC

The authentication is done for me, under the hood.

The disadvantages

As the above example shows, in terms of convenience ssh-agent is very helpful. However, there are a couple of minor security risks associated with its use.

Firstly, letting ssh-agent handle your public and private keys is just adding another thing that could go wrong. What if under some circumstances, ssh-agent reveals your private key? What if it's vulnerable to a man in the middle attack, or a reflection attack? There have been a couple of security warnings to do with ssh-agent, but as the program only authenticates you to others, rather than the other way round, this is a low risk threat.

Also, as ssh-agent allows authentication throughout a session, if you leave your keyboard for a few minutes, anyone can walk up and connect to any machines you could, with as little trouble as you had. Obviously, taking care to lock your screen when you go for a coffee will prevent this from happening.

How to use ssh-agent

The basic idea is to make ssh-agent the first userspace program started in an X session, then let each of the user's future processes be a child of it. In this way, we can guarantee all a user's processes will be aware of ssh-agent, and will be able to take advantage of its features. How to do this will depend on how you start X on your machine, and to some extent, what distribution you use.


Before attempting the following, you should have created your keypair and distributed the public key to whatever servers you will access. This is not the place to describe the process - see man ssh-keygen.

Also, you should check that your distribution does not start ssh-agent automatically - Debian does by default. You can find out by either looking for an ssh-agent process:

~ $ ps uax | grep 'ssh-agent'
or checking /etc/X11/Xsession.options for a line:

If ssh-agent is started automatically, you can leave go straight to the "Adding your keypairs to ssh-agent" section.

Manual X startup

This applies to anyone who types startx, or any of the other xinit wrappers, such as openwin, at a command line in order to start an X session.

If this includes you, you're lucky, all you need to do is insert ssh-agent before your command:

 $ startx
 $ ssh-agent startx

Now see "Adding your keypairs to ssh-agent"

Automatic X startup

If you are greeted by a login screen automatically, you will need to edit your X server startup scripts. How to do this varies from distro to distro, but most have a personal X startup script in the user's home directory, normally, but not necessarily, called .xsession.

What we will do is move the existing .xsession file to .xsession-script, then call that from a new .xsession file:

~ $ mv -i .xsession .xsession-script
~ $ cat > .xsession
/path/to/ssh-agent ~/.xsession-script
~ $ chmod u+x .xsession

Now your previous .xsession script is all run as a child of ssh-agent - just what we want.

Adding your keypairs to ssh-agent

All you need to do now is let ssh-agent know about the keypair you created above. You can do this by adding a line to your ~/.xsession file (or ~/.xsession-script if you created that as shown above):

/bin/sh -c "/usr/bin/ssh-add" &

This will prompt you for your passphrase as you log in.


As well as making remote access more convenient for users, ssh-agent also means that tools such as ssh and scp can be used in scripts, whereas before, the requirement of a password meant only interactive use was possible. If a user needs to backup some sensitive files every night, this sort of functionality is indispensable.

Steve Allen's SSH index -