1keychain(1)                  http://www.funtoo.org                 keychain(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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
23       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
29       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
41       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
48       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
52       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
56       Keychain supports most UNIX-like operating systems, including Cygwin.
57       It works with Bourne-compatible, csh-compatible and fish shells.
58

OPTIONS

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
65       --attempts num
66           Try num times to add keys before giving up.  The default is 1.
67
68       --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
75       --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
81       --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
86       --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
91       --dir dirname
92           Keychain will use dirname rather than $HOME/.keychain
93
94       --query
95           Keychain will print lines in KEY=value format representing the
96           values which are set by the agents.
97
98       --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
103       --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
111       --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
115       -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
119       --host name
120           Set alternate hostname for creation of pidfiles
121
122       --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
128       --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
133           local       Inherit when a pid (e.g. SSH_AGENT_PID) is set in the
134                       environment.  This disallows inheriting a forwarded
135                       agent.
136
137           any         Inherit when a sock (e.g. SSH_AUTH_SOCK) is set in the
138                       environment.  This allows inheriting a forwarded agent.
139
140           local-once  Same as "local", but only inherit if keychain isn't
141                       already providing an agent.
142
143           any-once    Same as "any", but only inherit if keychain isn't
144                       already providing an agent.
145
146           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
150       -l --list
151           List signatures of all active SSH keys, and exit, similar to "ssh-
152           add -l".
153
154       -L --list-fp
155           List fingerprints of all active SSH keys, and exit, similar to
156           "ssh-add -L".
157
158       --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
164       --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
170       --nocolor
171           Disable color highlighting for non ANSI-compatible terms.
172
173       --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
177       --noinherit
178           Don't inherit any agent processes, overriding the default
179           "--inherit local-once"
180
181       --nolock
182           Don't attempt to use a lockfile while manipulating files, pids and
183           keys.
184
185       -k --stop which
186           Kill currently running agent processes.  The following values are
187           valid for "which":
188
189           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
193           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
198           mine     Kill keychain's agent processes, leaving other agents
199                    alone.
200
201       --systemd
202           Inject environment variables into the systemd --user session.
203
204       -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
210       -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
215       --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
224           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
231       -V --version
232           Show version information.
233

EXAMPLES

235       This snippet should work in most shells to load two ssh keys and one
236       gpg key:
237
238           eval `keychain --eval id_rsa id_dsa 0123ABCD`
239
240       For the fish shell, use the following format:
241
242           if status --is-interactive
243               keychain --eval --quiet -Q id_rsa | source
244           end
245
246       If you have trouble with that in csh:
247
248           setenv SHELL /bin/csh
249           eval `keychain --eval id_rsa id_dsa 0123ABCD`
250
251       This is equivalent for Bourne shells (including bash and zsh) but
252       doesn't use keychain's --eval feature:
253
254           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
261       This is equivalent for C shell (including tcsh):
262
263           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
272       To load keychain variables from a script (for example from cron) and
273       abort unless id_dsa is available:
274
275           # 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

SEE ALSO

281       ssh-agent(1)
282

NOTES

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>.
289
290
291
2922.8.5                             2018-01-24                       keychain(1)
Impressum