Ubuntu Manpage: keychain - re-use ssh-agent and/or gpg-agent between logins

NAME

       keychain - re-use ssh-agent and/or gpg-agent between logins

SYNOPSIS

       keychain [ -hkQqV ] [ --clear --help --ignore-missing --noask
       --nocolor --nogui --nolock --quick --quiet --version ]
       [ --agents list ] [ --attempts num ] [ --dir dirname ]
       [ --host name ] [ --lockwait seconds ] [ --stop which ] [ --timeout minutes ] [ keys... ]

DESCRIPTION

       keychain is a manager for ssh-agent, typically run from ~/.bash_profile.  It allows your
       shells and cron jobs to share a single ssh-agent process.  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 want to change this behavior, take a look at the --clear and
       --timeout options, described below.

       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
       Bourne-compatible, csh-compatible and fish shells.

OPTIONS

--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.

--confirm
Keys are subject to interactive confirmation by the SSH_ASKPASS program before being
used for authentication. See the -c option for ssh-add(1).

--dir dirname
Keychain will use dirname rather than $HOME/.keychain

--eval
Keychain will print lines to be evaluated in the shell on stdout. It respects the
SHELL environment variable to determine if Bourne shell or C shell output is expected.

--env filename
After parsing options, keychain will load additional environment settings from
"filename". By default, if "--env" is not given, then keychain will attempt to load
from ~/.keychain/[hostname]-env or alternatively ~/.keychain/env. The purpose of this
file is to override settings such as PATH, in case ssh is stored in a non-standard
place.

-h --help
Show help that looks remarkably like this man-page. As of 2.6.10, help is sent to
stdout so it can be easily piped to a pager.

--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 5 seconds. Specify a
value of zero or more. If the lock cannot be acquired within the specified number of
seconds, then this keychain process will forcefully acquire the lock.

--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. As of version
2.6.10, this also suppresses "Identities added" messages for ssh-agent.

--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.

EXAMPLES

       This snippet should work in any shell to load two ssh keys and one gpg key:

           eval `keychain --eval id_rsa id_dsa 0123ABCD`

       If you have trouble with that in csh:

           setenv SHELL /bin/csh
           eval `keychain --eval id_rsa id_dsa 0123ABCD`

       This is equivalent for Bourne shells (including bash and zsh) but doesn't use keychain's
       --eval feature:

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

       This is equivalent for C shell (including tcsh):

           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

       To load keychain variables from a script (for example from cron) and abort unless id_dsa
       is available:

           # Load keychain variables and check for id_dsa
           [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`
           . $HOME/.keychain/$HOSTNAME-sh 2>/dev/null
           ssh-add -l 2>/dev/null | grep -q id_dsa || exit 1

NOTES