1keychain(1) http://gentoo.org/proj/en/keychain.xml keychain(1)
2
6 keychain - re-use ssh-agent and/or gpg-agent between logins
7
9 keychain [ -hkQqV ] [ --clear --help --ignore-missing --noask
10 --nocolor --nogui --nolock --quick --quiet --version ]
11 [ --agents list ] [ --attempts num ] [ --dir dirname ]
12 [ --host name ] [ --lockwait seconds ] [ --stop which ] [ --time‐
13 out minutes ] [ keys... ]
14
16 keychain is a manager for ssh-agent, typically run from ~/.bash_pro‐
17 file. It allows your shells and cron jobs to share a single ssh-agent
18 process. By default, the ssh-agent started by keychain is long-running
19 and will continue to run, even after you have logged out from the sys‐
20 tem. If you want to change this behavior, take a look at the --clear
21 and --timeout options, described below.
22 When keychain is run, it checks for a running ssh-agent, otherwise it
24 starts one. It saves the ssh-agent environment variables to ~/.key‐
25 chain/${HOSTNAME}-sh, so that subsequent logins and non-interactive
26 shells such as cron jobs can source the file and make passwordless ssh
27 connections. In addition, when keychain runs, it verifies that the key
28 files specified on the command-line are known to ssh-agent, otherwise
29 it loads them, prompting you for a password if necessary.
30 Keychain also supports gpg-agent in the same ways that ssh-agent is
32 supported. By default keychain attempts to start all available agents
33 but will fall back to only gpg-agent or only ssh-agent if either is
34 unavailable. You can specifically limit keychain using the --agents
35 option.
36 keychain supports most UNIX-like operating systems, including Cygwin.
38 It works with Bourne-compatible, csh-compatible and fish shells.
39
41 --agents list
42 Start the agents listed. By default keychain will build the list
43 automatically based on the existence of ssh-agent and/or gpg-agent
44 on the system. The list should be comma-separated, for example
45 "gpg,ssh"
46 --attempts num
48 Try num times to add keys before giving up. The default is 1.
49 --clear
51 Delete all of ssh-agent's keys. Typically this is used in
52 .bash_profile. The theory behind this is that keychain should
53 assume that you are an intruder until proven otherwise. However,
54 while this option increases security, it still allows your cron
55 jobs to use your ssh keys when you're logged out.
56 --confirm
58 Keys are subject to interactive confirmation by the SSH_ASKPASS
59 program before being used for authentication. See the -c option
60 for ssh-add(1).
61 --dir dirname
63 Keychain will use dirname rather than $HOME/.keychain
64 --eval
66 Keychain will print lines to be evaluated in the shell on stdout.
67 It respects the SHELL environment variable to determine if Bourne
68 shell or C shell output is expected.
69 --env filename
71 After parsing options, keychain will load additional environment
72 settings from "filename". By default, if "--env" is not given,
73 then keychain will attempt to load from ~/.keychain/[hostname]-env
74 or alternatively ~/.keychain/env. The purpose of this file is to
75 override settings such as PATH, in case ssh is stored in a non-
76 standard place.
77 -h --help
79 Show help that looks remarkably like this man-page.
80 --host name
82 Set alternate hostname for creation of pidfiles
83 --ignore-missing
85 Don't warn if some keys on the command-line can't be found. This
86 is useful for situations where you have a shared .bash_profile, but
87 your keys might not be available on every machine where keychain is
88 run.
89 --inherit which
91 Attempt to inherit agent variables from the environment. This can
92 be useful in a variety of circumstances, for example when ssh-agent
93 is started by gdm. The following values are valid for "which":
94 local Inherit when a pid (e.g. SSH_AGENT_PID) is set in the
96 environment. This disallows inheriting a forwarded
97 agent.
98 any Inherit when a sock (e.g. SSH_AUTH_SOCK) is set in the
100 environment. This allows inheriting a forwarded agent.
101 local-once Same as "local", but only inherit if keychain isn't
103 already providing an agent.
104 any-once Same as "any", but only inherit if keychain isn't
106 already providing an agent.
107 By default, keychain-2.5.0 and later will behave as if "--inherit
109 local-once" is specified. You should specify "--noinherit" if you
110 want the older behavior.
111 --lockwait seconds
113 How long to wait for the lock to become available. Defaults to 30
114 seconds. -1 indicates to wait forever.
115 --noask
117 This option tells keychain do everything it normally does (ensure
118 ssh-agent is running, set up the ~/.keychain/[hostname]-{c}sh
119 files) except that it will not prompt you to add any of the keys
120 you specified if they haven't yet been added to ssh-agent.
121 --nocolor
123 Disable color hilighting for non ANSI-compatible terms.
124 --nogui
126 Don't honor SSH_ASKPASS, if it is set. This will cause ssh-add to
127 prompt on the terminal instead of using a graphical program.
128 --noinherit
130 Don't inherit any agent processes, overriding the default
131 "--inherit local-once"
132 --nolock
134 Don't attempt to use a lockfile while manipulating files, pids and
135 keys.
136 -k --stop which
138 Kill currently running agent processes. The following values are
139 valid for "which":
140 all Kill all agent processes and quit keychain immediately.
142 Prior to keychain-2.5.0, this was the behavior of the bare
143 "--stop" option.
144 others Kill agent processes other than the one keychain is pro‐
146 viding. Prior to keychain-2.5.0, keychain would do this
147 automatically. The new behavior requires that you specify
148 it explicitly if you want it.
149 mine Kill keychain's agent processes, leaving other agents
151 alone.
152 -Q --quick
154 If an ssh-agent process is running then use it. Don't verify the
155 list of keys, other than making sure it's non-empty. This option
156 avoids locking when possible so that multiple terminals can be
157 opened simultaneously without waiting on each other.
158 -q --quiet
160 Only print messages in case of warning, error or required interac‐
161 tivity.
162 --timeout minutes
164 Set a timeout in minutes on your keys. This is conveyed to ssh-
165 agent which does the actual timing out of keys since keychain
166 doesn't run continuously.
167 -V --version
169 Show version information.
170
172 Note that the examples below assume that keychain is available on the
173 machine they're run. If you're using them in your login profile snip‐
174 pets that are shared between systems, it may be a good idea to protect
175 their invocation by first checking if keychain is indeed available.
176 This snippet should work in any shell to load two ssh keys (id_rsa and
178 id_dsa) and one gpg key (key id 0123ABCD):
179 eval `keychain --eval id_rsa id_dsa 0123ABCD`
181 If you have trouble with that in csh:
183 setenv SHELL /bin/csh
185 eval `keychain --eval id_rsa id_dsa 0123ABCD`
186 This is equivalent for Bourne shells (including bash and zsh) but
188 doesn't use keychain's --eval feature:
189 keychain id_rsa id_dsa 0123ABCD
191 [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`
192 [ -f $HOME/.keychain/$HOSTNAME-sh ] && \
193 . $HOME/.keychain/$HOSTNAME-sh
194 [ -f $HOME/.keychain/$HOSTNAME-sh-gpg ] && \
195 . $HOME/.keychain/$HOSTNAME-sh-gpg
196 This is equivalent for C shell (including tcsh):
198 keychain id_rsa id_dsa 0123ABCD
200 host=`uname -n`
201 if (-f $HOME/.keychain/$host-csh) then
202 source $HOME/.keychain/$host-csh
203 endif
204 if (-f $HOME/.keychain/$host-csh-gpg) then
205 source $HOME/.keychain/$host-csh-gpg
206 endif
207 To load keychain variables from a script (for example from cron) and
209 abort unless id_dsa is available:
210 # Load keychain variables and check for id_dsa
212 [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`
213 . $HOME/.keychain/$HOSTNAME-sh 2>/dev/null
214 ssh-add -l 2>/dev/null ⎪ grep -q id_dsa ⎪⎪ exit 1
215
217 ssh-agent(1)
218
220 Keychain is maintained by Aron Griffis <agriffis@gentoo.org>. If you
221 need to report a bug or request an enhancement, please do so at
222 <http://bugs.gentoo.org/> and assign to agriffis@gentoo.org
223 Keychain was originally written by Daniel Robbins <drobbins@gen‐
225 too.org>, who has also written a series of three articles about it.
226 The articles can be found starting at <http://www-106.ibm.com/develop‐
227 erworks/library/l-keyc.html>
2282.6.8 2006-09-08 keychain(1)