When keychain is run, it checks for a running ssh-agent, otherwise it starts one. It saves the ssh-agent environment variables to ~/.keychain/${HOSTNAME}-sh, so that subsequent logins and non-interactive shells such as cron jobs can source the file and make passwordless ssh connections. In addition, when keychain runs, it verifies that the key files specified on the command-line are known to ssh-agent, otherwise it loads them, prompting you for a password if necessary.

Keychain also supports gpg-agent in the same ways that ssh-agent is supported. By default keychain attempts to start all available agents but will fall back to only gpg-agent or only ssh-agent if either is unavailable. You can specifically limit keychain using the --agents option.

keychain supports most UNIX-like operating systems, including Cygwin. It works with both Bourne-compatible and csh-compatible shells.

--agents list

Start the agents listed. By default keychain will build the list automatically based on the existence of ssh-agent and/or gpg-agent on the system. The list should be comma-separated, for example ``gpg,ssh''

--attempts num

Try num times to add keys before giving up. The default is 1.

--clear

Delete all of ssh-agent's keys. Typically this is used in .bash_profile. The theory behind this is that keychain should assume that you are an intruder until proven otherwise. However, while this option increases security, it still allows your cron jobs to use your ssh keys when you're logged out.

--dir dirname

Keychain will use dirname rather than $HOME/.keychain

-h --help

Show help that looks remarkably like this man-page.

--host name

Set alternate hostname for creation of pidfiles

--ignore-missing

Don't warn if some keys on the command-line can't be found. This is useful for situations where you have a shared .bash_profile, but your keys might not be available on every machine where keychain is run.

--inherit which

Attempt to inherit agent variables from the environment. This can be useful in a variety of circumstances, for example when ssh-agent is started by gdm. The following values are valid for ``which'':

local

Inherit when a pid (e.g. SSH_AGENT_PID) is set in the environment. This disallows inheriting a forwarded agent.

any

Inherit when a sock (e.g. SSH_AUTH_SOCK) is set in the environment. This allows inheriting a forwarded agent.

local-once

Same as ``local'', but only inherit if keychain isn't already providing an agent.

any-once

Same as ``any'', but only inherit if keychain isn't already providing an agent.

By default, keychain-2.5.0 and later will behave as if ``--inherit local-once'' is specified. You should specify ``--noinherit'' if you want the older behavior.

--lockwait seconds

How long to wait for the lock to become available. Defaults to 30 seconds.

--noask

This option tells keychain do everything it normally does (ensure ssh-agent is running, set up the ~/.keychain/[hostname]-{c}sh files) except that it will not prompt you to add any of the keys you specified if they haven't yet been added to ssh-agent.

--nocolor

Disable color hilighting for non ANSI-compatible terms.

--nogui

Don't honor SSH_ASKPASS, if it is set. This will cause ssh-add to prompt on the terminal instead of using a graphical program.

--noinherit

Don't inherit any agent processes, overriding the default ``--inherit local-once''

--nolock

Don't attempt to use a lockfile while manipulating files, pids and keys.

-k --stop which

Kill currently running agent processes. The following values are valid for ``which'':

all

Kill all agent processes and quit keychain immediately. Prior to keychain-2.5.0, this was the behavior of the bare ``--stop'' option.

others

Kill agent processes other than the one keychain is providing. Prior to keychain-2.5.0, keychain would do this automatically. The new behavior requires that you specify it explicitly if you want it.

mine

Kill keychain's agent processes, leaving other agents alone.

-Q --quick

If an ssh-agent process is running then use it. Don't verify the list of keys, other than making sure it's non-empty. This option avoids locking when possible so that multiple terminals can be opened simultaneously without waiting on each other.

-q --quiet

Only print messages in case of warning, error or required interactivity.

--timeout minutes

Set a timeout in minutes on your keys. This is conveyed to ssh-agent which does the actual timing out of keys since keychain doesn't run continuously.

-V --version

Show version information.

    keychain id_rsa id_dsa 0123ABCD
        [[ -f $HOME/.keychain/$HOSTNAME-sh ]] && \
                source $HOME/.keychain/$HOSTNAME-sh
        [[ -f $HOME/.keychain/$HOSTNAME-sh-gpg ]] && \
                source  $HOME/.keychain/$HOSTNAME-sh-gpg

For other Bourne-compatible shells such as sh, you can use this in .profile:

    keychain id_rsa id_dsa 0123ABCD
        host=`uname -n`
        [ -f $HOME/.keychain/$host-sh ] && \
                . $HOME/.keychain/$host-sh
        [ -f $HOME/.keychain/$host-sh-gpg ] && \
                . $HOME/.keychain/$host-sh-gpg

This snippet would work in .login for tcsh:

    keychain id_rsa id_dsa 0123ABCD
        if (-f $HOME/.keychain/$HOST-csh) then
                source $HOME/.keychain/$HOST-csh
        endif
        if (-f $HOME/.keychain/$HOST-csh-gpg) then
                source $HOME/.keychain/$HOST-csh-gpg
        endif

This snippet would work in .login for csh:

    keychain id_rsa id_dsa 0123ABCD
        host=`uname -n`
        if (-f $HOME/.keychain/$host-csh) then
                source $HOME/.keychain/$host-csh
        endif
        if (-f $HOME/.keychain/$host-csh-gpg) then
                source $HOME/.keychain/$host-csh-gpg
        endif

Keychain was originally written by Daniel Robbins <drobbins@gentoo.org>, who has also written a series of three articles about it. The articles can be found starting at <http://www-106.ibm.com/developerworks/library/l-keyc.html>