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

--agentslist
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"
--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.
--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).
--dirdirname
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.
--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.
-h--help
Show help that looks remarkably like this man-page.
--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.
--lockwaitseconds
How long to wait for the lock to become available. Defaults to 30
seconds. -1 indicates to wait forever.
--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--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.
-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.
--timeoutminutes
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.