1keychain(1) http://www.funtoo.org keychain(1)
2
6 keychain - re-use ssh-agent and/or gpg-agent between logins
7
9 keychain [ -hklQqV ] [ --clear --confhost --gpg2 --help --ignore-missing --list
10 --noask --nocolor --nogui --nolock --quick --quiet --version ]
11 [ --agents list ] [ --attempts num ] [ --dir dirname ]
12 [ --host name ] [ --lockwait seconds ]
13 [ --stop which ] [ --timeout minutes ] [ keys... ]
14
16 keychain is a manager for ssh-agent, typically run from
17 ~/.bash_profile. It allows your shells and cron jobs to easily share a
18 single ssh-agent process. By default, the ssh-agent started by
19 keychain is long-running and will continue to run, even after you have
20 logged out from the system. If you want to change this behavior, take
21 a look at the --clear 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
25 ~/.keychain/${HOSTNAME}-sh, so that subsequent logins and non-
26 interactive shells such as cron jobs can source the file and make
27 passwordless ssh connections.
28 In addition, when keychain runs, it verifies that the key files
30 specified on the command-line are known to ssh-agent, otherwise it
31 loads them, prompting you for a password if necessary. Typically,
32 private key files are specified by filename only, without path,
33 although it is possible to specify an absolute or relative path to the
34 private key file as well. If just a private key filename is used, which
35 is typical usage, keychain will look for the specified private key
36 files in ~/.ssh, ~/.ssh2, or with the -c/--confhost option, inspect the
37 ~/.ssh/config file and use the IdentityFile option to determine the
38 location of the private key. Private keys can be symlinks to the actual
39 private key.
40 Keychain expects associated public key files to exist in the same
42 directory as the private key files, with a .pub extension. If the
43 private key is a symlink, the public key can be found alongside the
44 symlink, or in the same directory as the symlink target (This
45 capability requires the 'readlink' command to be available on the
46 system.)
47 As an additional feature, if a private key has an extension ".ext",
49 keychain will look for privkey.ext.pub first, and if not found, will
50 look for privkeyname.pub.
51 Keychain also supports gpg-agent in the same ways that ssh-agent is
53 supported. By default keychain attempts to start ssh-agent only. You
54 can modify this behavior using the --agents option.
55 Keychain supports most UNIX-like operating systems, including Cygwin.
57 It works with Bourne-compatible, csh-compatible and fish shells.
58
60 --agents list
61 Start the agents listed. By default keychain will start ssh-agent
62 if it is found in your path. The list should be comma-separated,
63 for example "gpg,ssh"
64 --attempts num
66 Try num times to add keys before giving up. The default is 1.
67 --clear
69 Delete all of ssh-agent's keys. Typically this is used in
70 .bash_profile. The theory behind this is that keychain should
71 assume that you are an intruder until proven otherwise. However,
72 while this option increases security, it still allows your cron
73 jobs to use your ssh keys when you're logged out.
74 --confhost
76 By default, keychain will look for key pairs in the ~/.ssh/
77 directory. The --confhost option will inform keychain to look in
78 ~/.ssh/config for IdentityFile settings defined for particular
79 hosts, and use these paths to locate keys.
80 --confirm
82 Keys are subject to interactive confirmation by the SSH_ASKPASS
83 program before being used for authentication. See the -c option
84 for ssh-add(1).
85 --absolute
87 Any arguments to "--dir" are interpreted to be absolute. The
88 default behavior is to append "/.keychain" to the argument for
89 backwards compatibility.
90 --dir dirname
92 Keychain will use dirname rather than $HOME/.keychain
93 --query
95 Keychain will print lines in KEY=value format representing the
96 values which are set by the agents.
97 --eval
99 Keychain will print lines to be evaluated in the shell on stdout.
100 It respects the SHELL environment variable to determine if Bourne
101 shell or C shell output is expected.
102 --env filename
104 After parsing options, keychain will load additional environment
105 settings from "filename". By default, if "--env" is not given,
106 then keychain will attempt to load from ~/.keychain/[hostname]-env
107 or alternatively ~/.keychain/env. The purpose of this file is to
108 override settings such as PATH, in case ssh is stored in a non-
109 standard place.
110 --gpg2
112 This option changes the default gpg calls to use gpg2 instead to
113 support distributions such as Ubuntu which has both gpg and gpg2
114 -h --help
116 Show help that looks remarkably like this man-page. As of 2.6.10,
117 help is sent to stdout so it can be easily piped to a pager.
118 --host name
120 Set alternate hostname for creation of pidfiles
121 --ignore-missing
123 Don't warn if some keys on the command-line can't be found. This
124 is useful for situations where you have a shared .bash_profile, but
125 your keys might not be available on every machine where keychain is
126 run.
127 --inherit which
129 Attempt to inherit agent variables from the environment. This can
130 be useful in a variety of circumstances, for example when ssh-agent
131 is started by gdm. The following values are valid for "which":
132 local Inherit when a pid (e.g. SSH_AGENT_PID) is set in the
134 environment. This disallows inheriting a forwarded
135 agent.
136 any Inherit when a sock (e.g. SSH_AUTH_SOCK) is set in the
138 environment. This allows inheriting a forwarded agent.
139 local-once Same as "local", but only inherit if keychain isn't
141 already providing an agent.
142 any-once Same as "any", but only inherit if keychain isn't
144 already providing an agent.
145 By default, keychain-2.5.0 and later will behave as if "--inherit
147 local-once" is specified. You should specify "--noinherit" if you
148 want the older behavior.
149 -l --list
151 List signatures of all active SSH keys, and exit, similar to "ssh-
152 add -l".
153 -L --list-fp
155 List fingerprints of all active SSH keys, and exit, similar to
156 "ssh-add -L".
157 --lockwait seconds
159 How long to wait for the lock to become available. Defaults to 5
160 seconds. Specify a value of zero or more. If the lock cannot be
161 acquired within the specified number of seconds, then this keychain
162 process will forcefully acquire the lock.
163 --noask
165 This option tells keychain do everything it normally does (ensure
166 ssh-agent is running, set up the ~/.keychain/[hostname]-{c}sh
167 files) except that it will not prompt you to add any of the keys
168 you specified if they haven't yet been added to ssh-agent.
169 --nocolor
171 Disable color highlighting for non ANSI-compatible terms.
172 --nogui
174 Don't honor SSH_ASKPASS, if it is set. This will cause ssh-add to
175 prompt on the terminal instead of using a graphical program.
176 --noinherit
178 Don't inherit any agent processes, overriding the default
179 "--inherit local-once"
180 --nolock
182 Don't attempt to use a lockfile while manipulating files, pids and
183 keys.
184 -k --stop which
186 Kill currently running agent processes. The following values are
187 valid for "which":
188 all Kill all agent processes and quit keychain immediately.
190 Prior to keychain-2.5.0, this was the behavior of the bare
191 "--stop" option.
192 others Kill agent processes other than the one keychain is
194 providing. Prior to keychain-2.5.0, keychain would do
195 this automatically. The new behavior requires that you
196 specify it explicitly if you want it.
197 mine Kill keychain's agent processes, leaving other agents
199 alone.
200 --systemd
202 Inject environment variables into the systemd --user session.
203 -Q --quick
205 If an ssh-agent process is running then use it. Don't verify the
206 list of keys, other than making sure it's non-empty. This option
207 avoids locking when possible so that multiple terminals can be
208 opened simultaneously without waiting on each other.
209 -q --quiet
211 Only print messages in case of warning, error or required
212 interactivity. As of version 2.6.10, this also suppresses
213 "Identities added" messages for ssh-agent.
214 --timeout minutes
216 Allows a timeout to be set for identities added to ssh-agent. When
217 this option is used with a keychain invocation that starts ssh-
218 agent itself, then keychain uses the appropriate ssh-agent option
219 to set the default timeout for ssh-agent. The --timeout option
220 also gets passed to ssh-add invocations, so any keys added to a
221 running ssh-agent will be individually configured to have the
222 timeout specified, overriding any ssh-agent default.
223 Most users can simply use the timeout setting they desire and get
225 the result they want -- with all identities having the specified
226 timeout, whether added by keychain or not. More advanced users can
227 use one invocation of keychain to set the default timeout, and
228 optionally set different timeouts for keys added by using a
229 subsequent invocation of keychain.
230 -V --version
232 Show version information.
233
235 This snippet should work in most shells to load two ssh keys and one
236 gpg key:
237 eval `keychain --eval id_rsa id_dsa 0123ABCD`
239 For the fish shell, use the following format:
241 if status --is-interactive
243 keychain --eval --quiet -Q id_rsa | source
244 end
245 If you have trouble with that in csh:
247 setenv SHELL /bin/csh
249 eval `keychain --eval id_rsa id_dsa 0123ABCD`
250 This is equivalent for Bourne shells (including bash and zsh) but
252 doesn't use keychain's --eval feature:
253 keychain id_rsa id_dsa 0123ABCD
255 [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`
256 [ -f $HOME/.keychain/$HOSTNAME-sh ] && \
257 . $HOME/.keychain/$HOSTNAME-sh
258 [ -f $HOME/.keychain/$HOSTNAME-sh-gpg ] && \
259 . $HOME/.keychain/$HOSTNAME-sh-gpg
260 This is equivalent for C shell (including tcsh):
262 keychain id_rsa id_dsa 0123ABCD
264 host=`uname -n`
265 if (-f $HOME/.keychain/$host-csh) then
266 source $HOME/.keychain/$host-csh
267 endif
268 if (-f $HOME/.keychain/$host-csh-gpg) then
269 source $HOME/.keychain/$host-csh-gpg
270 endif
271 To load keychain variables from a script (for example from cron) and
273 abort unless id_dsa is available:
274 # Load keychain variables and check for id_dsa
276 [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`
277 . $HOME/.keychain/$HOSTNAME-sh 2>/dev/null
278 ssh-add -l 2>/dev/null | grep -q id_dsa || exit 1
279
281 ssh-agent(1)
282
284 Keychain was created and is currently maintained by Daniel Robbins. If
285 you need to report a bug or request an enhancement, please post to the
286 Funtoo Linux bug tracker <http://bugs.funtoo.org>. For more
287 information about keychain, please visit
288 <http://www.funtoo.org/Keychain>.
2892.8.5 2018-01-24 keychain(1)