KEYCHAIN(1)

NAME
keychain - a program designed to keep ssh-agent processes alive across multiple logins.

SYNOPSIS
keychain [options] [keys...]

DESCRIPTION
Keychain(1) is an OpenSSH key manager, typically run from ~/.profile. When run, it will make sure ssh-agent is running; if not, it will start ssh-agent. It will redirect ssh-agent's output to ~/.keychain/[hostname]-sh, so that cron jobs that need to use ssh-agent keys can simply source this file and make the necessary passwordless ssh connections. In addition, when keychain runs, it will check with ssh-agent and make sure that the ssh RSA/DSA keys that you specified on the keychain command line have actually been added to ssh-agent. If not, you are prompted for the appropriate passphrases so that they can be added by keychain.

USAGE
Typically, one uses keychain by adding the following to the top of their ~/.profile (or ~/.zlogin, in case of zsh):

    keychain ~/.ssh/id_rsa ~/.ssh/id_dsa
    . ~/.keychain/${HOSTNAME}-sh

# alt. syntax: . ~/.keychain/`uname -n`-sh
# note the use of back-quotes (`) rather than single-quotes (') above.
# We now include the hostname (`uname -n`) in the keychain filename
# for NFS-compatibility.

You can make keychain work with your csh-compatible shell by adding the following to your .cshrc:

keychain ~/.ssh/id_rsa ~/.ssh/id_dsa
source ~/.keychain/${HOSTNAME}-csh

Keychain allows all your apps and cron jobs to use a single ssh-agent process as an authentication agent. By default, the ssh-agent started by keychain is long-running and will continue to run, even after you have logged out from the system. If you'd like to tighten up security a bit, take a look at the --clear option, described below.

OPTIONS

--clear
    Tells keychain to delete all of ssh-agent's host keys. Typically, This is used in the ~/.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 [directoryname]
    Keychain will look in [directoryname] for the .keychain file, rather than your home directory.

--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
    This option disables color highlighting for non vt-100-compatible terms.

--stop, -k
    This option tells keychain to stop all running ssh-agent processes, and then exit.

--quiet, -q
    This option tells keychain to turn off verbose mode and only print error messages and interactive messages. This is useful for login scripts etc.

BUGS
On some UNIX systems, keychain conflicts with the gnome session manager, which attempts to start an ssh-agent process of its own. This is fixed by modifying the global gnomerc file to use keychain as its ssh-agent instead of ssh-agent itself.

Please submit any keychain(1) bugs to http://bugs.gentoo.org under Gentoo Hosted Projects

AUTHORS
keychain(1) was written by Daniel Robbins <drobbins@gentoo.org> and is now maintained by Seth Chandler <sethbc@gentoo.org>.

SEE ALSO
ssh-agent(1)