1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
=head1 NAME
keychain - re-use ssh-agent and/or gpg-agent between logins
=head1 SYNOPSIS
S<keychain [ -hkQqV ] [ --clear --help --ignore-missing --noask>
S<--nocolor --nogui --nolock --quick --quiet --version ]>
S<[ --agents I<list> ] [ --attempts I<num> ] [ --dir I<dirname> ]>
S<[ --host I<name> ] [ --lockwait I<seconds> ]>
S<[ --stop I<which> ] [ --timeout I<minutes> ] [ keys... ]>
=head1 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 both Bourne-compatible and csh-compatible shells.
=head1 OPTIONS
=over
=item B<--agents> I<list>
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"
=item B<--attempts> I<num>
Try num times to add keys before giving up. The default is 1.
=item B<--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.
=item B<--dir> I<dirname>
Keychain will use dirname rather than $HOME/.keychain
=item B<-h --help>
Show help that looks remarkably like this man-page.
=item B<--host> I<name>
Set alternate hostname for creation of pidfiles
=item B<--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.
=item B<--inherit> I<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":
=over 12
=item B<local>
Inherit when a pid (e.g. SSH_AGENT_PID) is set in the environment.
This disallows inheriting a forwarded agent.
=item B<any>
Inherit when a sock (e.g. SSH_AUTH_SOCK) is set in the environment.
This allows inheriting a forwarded agent.
=item B<local-once>
Same as "local", but only inherit if keychain isn't already providing
an agent.
=item B<any-once>
Same as "any", but only inherit if keychain isn't already providing an
agent.
=back
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.
=item B<--lockwait> I<seconds>
How long to wait for the lock to become available. Defaults to 30
seconds.
=item B<--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.
=item B<--nocolor>
Disable color hilighting for non ANSI-compatible terms.
=item B<--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.
=item B<--noinherit>
Don't inherit any agent processes, overriding the default
"--inherit local-once"
=item B<--nolock>
Don't attempt to use a lockfile while manipulating files, pids and
keys.
=item B<-k --stop> I<which>
Kill currently running agent processes. The following values are
valid for "which":
=over 9
=item all
Kill all agent processes and quit keychain immediately. Prior to
keychain-2.5.0, this was the behavior of the bare "--stop" option.
=item 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.
=item mine
Kill keychain's agent processes, leaving other agents alone.
=back
=item B<-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.
=item B<-q --quiet>
Only print messages in case of warning, error or required
interactivity.
=item B<--timeout> I<minutes>
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.
=item B<-V --version>
Show version information.
=back
=head1 EXAMPLES
This snippet would work in .bash_profile (for bash) or .zlogin (for
zsh) to load two ssh keys and one gpg key:
keychain id_rsa id_dsa 0123ABCD
[[ -f $HOME/.keychain/$HOSTNAME-sh ]] && \
source $HOME/.keychain/$HOSTNAME-sh
[[ -f $HOME/.keychain/$HOSTNAME-sh-gpg ]] && \
source $HOME/.keychain/$HOSTNAME-sh-gpg
For other Bourne-compatible shells such as sh, you can use this in
.profile:
keychain id_rsa id_dsa 0123ABCD
host=`uname -n`
[ -f $HOME/.keychain/$host-sh ] && \
. $HOME/.keychain/$host-sh
[ -f $HOME/.keychain/$host-sh-gpg ] && \
. $HOME/.keychain/$host-sh-gpg
This snippet would work in .login for tcsh:
keychain id_rsa id_dsa 0123ABCD
if (-f $HOME/.keychain/$HOST-csh) then
source $HOME/.keychain/$HOST-csh
endif
if (-f $HOME/.keychain/$HOST-csh-gpg) then
source $HOME/.keychain/$HOST-csh-gpg
endif
This snippet would work in .login for csh:
keychain id_rsa id_dsa 0123ABCD
host=`uname -n`
if (-f $HOME/.keychain/$host-csh) then
source $HOME/.keychain/$host-csh
endif
if (-f $HOME/.keychain/$host-csh-gpg) then
source $HOME/.keychain/$host-csh-gpg
endif
=head1 SEE ALSO
L<ssh-agent(1)>
=head1 NOTES
Keychain is maintained by Aron Griffis <agriffis@gentoo.org>. If you
need to report a bug or request an enhancement, please do so at
L<http://bugs.gentoo.org/> and assign to agriffis@gentoo.org
Keychain was originally written by Daniel Robbins
<drobbins@gentoo.org>, who has also written a series of three articles
about it. The articles can be found starting at
L<http://www-106.ibm.com/developerworks/library/l-keyc.html>
=end
|
