Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
keychain(1)		   keychain(1)

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

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

       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

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

       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.

       --agents	list
	   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"

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

	   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.

	   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.

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

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

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

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

	   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.

	   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.

       --host name
	   Set alternate hostname for creation of pidfiles

	   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

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

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

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

	   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.

	   Disable color highlighting for non ANSI-compatible terms.

	   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 inherit any agent processes, overriding the default
	   "--inherit local-once"

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

       -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

	   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.

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

       -V --version
	   Show	version	information.

       This snippet should work	in most	shells to load two ssh keys and	one
       gpg key:

	   eval	`keychain --eval id_rsa	id_dsa 0123ABCD`

       For the fish shell, use the following format:

	   if status --is-interactive
	       keychain	--eval --quiet -Q id_rsa | source

       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
	   if (-f $HOME/.keychain/$host-csh-gpg) then
		   source $HOME/.keychain/$host-csh-gpg

       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


       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	<>.  For more
       information about keychain, please visit

2.8.5				  2018-01-24			   keychain(1)


Want to link to this manual page? Use this URL:

home | help