Secrets of ssh-agent

ssh-agent can be sneaky if you're not watching closely.  This command allows you to store your passphrase-protected SSH keys securely, but it doesn't work like most other commands.  

Unlike traditional commands, like cat or touch or renice, ssh-agent isn't invoked directly, and there's some prep-work that has to be done first.

Let's assume that you've got a shiny new server and a fancy new, 36 character passphrase-protected 2048 bit RSA SSH key.  Super secure, right?  But you don't want to have to manually enter that long password every time you want to use it, so you turn to good old ssh-agent to get the job done.

"Psssst.  Hey buddy," he says. "I can keep your passphrase safe an' get you into dat server anytime you want, but we gots ta do a few 'tings first.  See, da ssh command is owned by da shell - not you, not me, so we gotta go in all sideways-like."

He sidles closer. "You know eval, right?  Skinny guy, can execute arguments as shell commands?  If you throw him some $, he can load me up as a variable, then my buddy ssh-add - you know ssh-add?  Yeah, looks like a vole with a skin condition.  Once I'm good and loaded, you give him your key and tell him your passphrase.  He'll keep it safe.  Then, and here's the good part, whenever you come knocking and wanting to use that key and passphrase, I'm gonna go to my pal ssh-add, and he's gonna give ME that info, and I'm gonna put it in my auth-sock, then I'm gonna run it up to the shell up on the hill and give it to old ssh himself.  He's gonna run it up the line to your server and if everything checks out, you're in!  Got dat?  Da beauty is you don't gotta remember nuthin'!"

Now that the metaphor is stretched like - a big stretchy thing, let's recap in a more normal way.

To use ssh-agent, you first need to load it as a variable with eval, like this:
eval $(ssh-agent)

Then you can use ssh-add to add your key, like this:
ssh-add .ssh/key
And enter your passphrase when prompted.

When you start ssh-agent with eval, what you're actually doing is setting the path of the unix file socket that ssh-agent uses to communicate with other processes.  This is set in a variable called $SSH_AUTH_SOCK.

When you try to access a server that uses that key, ssh-agent will pass your key and passphrase to the ssh process, and bang - you're in!