/[gentoo-src]/keychain/keychain.pod
Gentoo

Contents of /keychain/keychain.pod

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.6 - (show annotations) (download)
Sat Jan 8 01:57:23 2005 UTC (9 years, 6 months ago) by agriffis
Branch: MAIN
CVS Tags: HEAD
Changes since 1.5: +63 -4 lines
- Makefile modifications to include only SYNOPSIS and OPTIONS in --help
- Add --inherit and --noinherit
- Make --inherit local-once the new default behavior
- Add parameters to --stop: all, others, mine
- Change default behavior so keychain doesn't stop other ssh-agents
  unless "--stop others" is specified

1 =head1 NAME
2
3 keychain - re-use ssh-agent and/or gpg-agent between logins
4
5 =head1 SYNOPSIS
6
7 S<keychain [ -hkQqV ] [ --clear --help --ignore-missing --noask>
8 S<--nocolor --nogui --nolock --quick --quiet --version ]>
9 S<[ --agents I<list> ] [ --attempts I<num> ] [ --dir I<dirname> ]>
10 S<[ --host I<name> ] [ --lockwait I<seconds> ]>
11 S<[ --stop I<which> ] [ --timeout I<minutes> ] [ keys... ]>
12
13 =head1 DESCRIPTION
14
15 keychain is a manager for ssh-agent, typically run from
16 ~/.bash_profile. It allows your shells and cron jobs to share a
17 single ssh-agent process. By default, the ssh-agent started by
18 keychain is long-running and will continue to run, even after you have
19 logged out from the system. If you want to change this behavior, take
20 a look at the --clear and --timeout options, described below.
21
22 When keychain is run, it checks for a running ssh-agent, otherwise it
23 starts one. It saves the ssh-agent environment variables to
24 ~/.keychain/${HOSTNAME}-sh, so that subsequent logins and
25 non-interactive shells such as cron jobs can source the file and make
26 passwordless ssh connections. In addition, when keychain runs, it
27 verifies that the key files specified on the command-line are known to
28 ssh-agent, otherwise it loads them, prompting you for a password if
29 necessary.
30
31 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
37 keychain supports most UNIX-like operating systems, including Cygwin.
38 It works with both Bourne-compatible and csh-compatible shells.
39
40 =head1 OPTIONS
41
42 =over
43
44 =item B<--agents> I<list>
45
46 Start the agents listed. By default keychain will build the list
47 automatically based on the existence of ssh-agent and/or gpg-agent on
48 the system. The list should be comma-separated, for example "gpg,ssh"
49
50 =item B<--attempts> I<num>
51
52 Try num times to add keys before giving up. The default is 1.
53
54 =item B<--clear>
55
56 Delete all of ssh-agent's keys. Typically this is used in
57 .bash_profile. The theory behind this is that keychain should assume
58 that you are an intruder until proven otherwise. However, while this
59 option increases security, it still allows your cron jobs to use your
60 ssh keys when you're logged out.
61
62 =item B<--dir> I<dirname>
63
64 Keychain will use dirname rather than $HOME/.keychain
65
66 =item B<-h --help>
67
68 Show help that looks remarkably like this man-page.
69
70 =item B<--host> I<name>
71
72 Set alternate hostname for creation of pidfiles
73
74 =item B<--ignore-missing>
75
76 Don't warn if some keys on the command-line can't be found. This is
77 useful for situations where you have a shared .bash_profile, but your
78 keys might not be available on every machine where keychain is run.
79
80 =item B<--inherit> I<which>
81
82 Attempt to inherit agent variables from the environment. This can be
83 useful in a variety of circumstances, for example when ssh-agent is
84 started by gdm. The following values are valid for "which":
85
86 =over 12
87
88 =item B<local>
89
90 Inherit when a pid (e.g. SSH_AGENT_PID) is set in the environment.
91 This disallows inheriting a forwarded agent.
92
93 =item B<any>
94
95 Inherit when a sock (e.g. SSH_AUTH_SOCK) is set in the environment.
96 This allows inheriting a forwarded agent.
97
98 =item B<local-once>
99
100 Same as "local", but only inherit if keychain isn't already providing
101 an agent.
102
103 =item B<any-once>
104
105 Same as "any", but only inherit if keychain isn't already providing an
106 agent.
107
108 =back
109
110 By default, keychain-2.5.0 and later will behave as if "--inherit
111 local-once" is specified. You should specify "--noinherit" if you
112 want the older behavior.
113
114 =item B<--lockwait> I<seconds>
115
116 How long to wait for the lock to become available. Defaults to 30
117 seconds.
118
119 =item B<--noask>
120
121 This option tells keychain do everything it normally does (ensure
122 ssh-agent is running, set up the ~/.keychain/[hostname]-{c}sh files)
123 except that it will not prompt you to add any of the keys you
124 specified if they haven't yet been added to ssh-agent.
125
126 =item B<--nocolor>
127
128 Disable color hilighting for non ANSI-compatible terms.
129
130 =item B<--nogui>
131
132 Don't honor SSH_ASKPASS, if it is set. This will cause ssh-add to
133 prompt on the terminal instead of using a graphical program.
134
135 =item B<--noinherit>
136
137 Don't inherit any agent processes, overriding the default
138 "--inherit local-once"
139
140 =item B<--nolock>
141
142 Don't attempt to use a lockfile while manipulating files, pids and
143 keys.
144
145 =item B<-k --stop> I<which>
146
147 Kill currently running agent processes. The following values are
148 valid for "which":
149
150 =over 9
151
152 =item all
153
154 Kill all agent processes and quit keychain immediately. Prior to
155 keychain-2.5.0, this was the behavior of the bare "--stop" option.
156
157 =item others
158
159 Kill agent processes other than the one keychain is providing. Prior
160 to keychain-2.5.0, keychain would do this automatically. The new
161 behavior requires that you specify it explicitly if you want it.
162
163 =item mine
164
165 Kill keychain's agent processes, leaving other agents alone.
166
167 =back
168
169 =item B<-Q --quick>
170
171 If an ssh-agent process is running then use it. Don't verify the list
172 of keys, other than making sure it's non-empty. This option avoids
173 locking when possible so that multiple terminals can be opened
174 simultaneously without waiting on each other.
175
176 =item B<-q --quiet>
177
178 Only print messages in case of warning, error or required
179 interactivity.
180
181 =item B<--timeout> I<minutes>
182
183 Set a timeout in minutes on your keys. This is conveyed to ssh-agent
184 which does the actual timing out of keys since keychain doesn't run
185 continuously.
186
187 =item B<-V --version>
188
189 Show version information.
190
191 =back
192
193 =head1 EXAMPLES
194
195 This snippet would work in .bash_profile (for bash) or .zlogin (for
196 zsh) to load two ssh keys and one gpg key:
197
198 keychain id_rsa id_dsa 0123ABCD
199 [[ -f $HOME/.keychain/$HOSTNAME-sh ]] && \
200 source $HOME/.keychain/$HOSTNAME-sh
201 [[ -f $HOME/.keychain/$HOSTNAME-sh-gpg ]] && \
202 source $HOME/.keychain/$HOSTNAME-sh-gpg
203
204 For other Bourne-compatible shells such as sh, you can use this in
205 .profile:
206
207 keychain id_rsa id_dsa 0123ABCD
208 host=`uname -n`
209 [ -f $HOME/.keychain/$host-sh ] && \
210 . $HOME/.keychain/$host-sh
211 [ -f $HOME/.keychain/$host-sh-gpg ] && \
212 . $HOME/.keychain/$host-sh-gpg
213
214 This snippet would work in .login for tcsh:
215
216 keychain id_rsa id_dsa 0123ABCD
217 if (-f $HOME/.keychain/$HOST-csh) then
218 source $HOME/.keychain/$HOST-csh
219 endif
220 if (-f $HOME/.keychain/$HOST-csh-gpg) then
221 source $HOME/.keychain/$HOST-csh-gpg
222 endif
223
224 This snippet would work in .login for csh:
225
226 keychain id_rsa id_dsa 0123ABCD
227 host=`uname -n`
228 if (-f $HOME/.keychain/$host-csh) then
229 source $HOME/.keychain/$host-csh
230 endif
231 if (-f $HOME/.keychain/$host-csh-gpg) then
232 source $HOME/.keychain/$host-csh-gpg
233 endif
234
235 =head1 SEE ALSO
236
237 L<ssh-agent(1)>
238
239 =head1 NOTES
240
241 Keychain is maintained by Aron Griffis <agriffis@gentoo.org>. If you
242 need to report a bug or request an enhancement, please do so at
243 L<http://bugs.gentoo.org/> and assign to agriffis@gentoo.org
244
245 Keychain was originally written by Daniel Robbins
246 <drobbins@gentoo.org>, who has also written a series of three articles
247 about it. The articles can be found starting at
248 L<http://www-106.ibm.com/developerworks/library/l-keyc.html>
249
250 =end

  ViewVC Help
Powered by ViewVC 1.1.20