keychain is a manager for ssh-agent, typically run from ~/.bash_profile. It
allows your shells and cron jobs to easily 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. Typically, private key files are specified by
filename only, without path, although it is possible to specify an absolute or
relative path to the private key file as well. If just a private key filename
is used, which is typical usage, keychain will look for the specified private
key files in ~/.ssh, ~/.ssh2, or with the -c/--confhost option, inspect the
~/.ssh/config file and use the IdentityFile option to determine the location
of the private key. Private keys can be symlinks to the actual private key.

Keychain expects associated public key files to exist in the same directory as
the private key files, with a .pub extension. If the private key is a symlink,
the public key can be found alongside the symlink, or in the same directory as
the symlink target (This capability requires the 'readlink' command to be
available on the system.)

As an additional feature, if a private key has an extension ".ext",
keychain will look for privkey.ext.pub first, and if not found, will look for
privkeyname.pub.

Keychain also supports gpg-agent in the same ways that ssh-agent is supported.
By default keychain attempts to start ssh-agent only. You can modify this
behavior using the --agents option.

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

Start the agents listed. By default keychain will start
ssh-agent if it is found in your path. The list should be comma-separated,
for example "gpg,ssh"

--attemptsnum

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.

--confhost

By default, keychain will look for key pairs in the ~/.ssh/
directory. The --confhost option will inform keychain to look in
~/.ssh/config for IdentityFile settings defined for particular hosts, and
use these paths to locate keys.

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

--absolute

Any arguments to "--dir" are interpreted to be
absolute. The default behavior is to append "/.keychain" to the
argument for backwards compatibility.

--dirdirname

Keychain will use dirname rather than $HOME/.keychain

--query

Keychain will print lines in KEY=value format representing
the values which are set by the agents.

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

--envfilename

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.

--gpg2

This option changes the default gpg calls to use gpg2
instead to support distributions such as Ubuntu which has both gpg and
gpg2

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

--hostname

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.

--inheritwhich

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.

-l --list

List signatures of all active SSH keys, and exit, similar
to "ssh-add -l".

-L --list-fp

List fingerprints of all active SSH keys, and exit, similar
to "ssh-add -L".

--lockwaitseconds

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

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

-k --stopwhich

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.

--systemd

Inject environment variables into the systemd --user
session.

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

--timeoutminutes

Allows a timeout to be set for identities added to
ssh-agent. When this option is used with a keychain invocation that starts
ssh-agent itself, then keychain uses the appropriate ssh-agent option to
set the default timeout for ssh-agent. The --timeout option also gets
passed to ssh-add invocations, so any keys added to a running ssh-agent
will be individually configured to have the timeout specified, overriding
any ssh-agent default.

Most users can simply use the timeout setting they desire and get the result
they want -- with all identities having the specified timeout, whether
added by keychain or not. More advanced users can use one invocation of
keychain to set the default timeout, and optionally set different timeouts
for keys added by using a subsequent invocation of keychain.

Keychain was created and is currently maintained by Daniel Robbins. If you need
to report a bug or request an enhancement, please post to the Funtoo Linux bug
tracker <http://bugs.funtoo.org>. For more information about keychain,
please visit <http://www.funtoo.org/Keychain>.