~ubuntu-branches/ubuntu/raring/keychain/raring : revision 6

1

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32

1

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)

2

.\"

3

.\" Standard preamble:

4

.\" ========================================================================

5

.de Sh \" Subsection heading

6

.br

7

.if t .Sp

8

.ne 5

9

.PP

10

\fB\\$1\fR

11

.PP

12

..

13

5

.de Sp \" Vertical space (when we can't use .PP)

14

6

.if t .sp .5v

15

7

.if n .sp

25

17

..

26

18

.\" Set up some character translations and predefined strings. \*(-- will

27

19

.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left

28

.\" double quote, and \*(R" will give a right double quote. | will give a

29

.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to

30

.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'

31

.\" expand to `' in nroff, nothing in troff, for use with C<>.

32

.tr \(*W-|\(bv\*(Tr

20

.\" double quote, and \*(R" will give a right double quote. \*(C+ will

21

.\" give a nicer C++. Capital omega is used to do unbreakable dashes and

22

.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,

23

.\" nothing in troff, for use with C<>.

24

.tr \(*W-

33

25

.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'

34

26

.ie n \{\

35

27

. ds -- \(*W-

48

40

. ds R" ''

49

41

.br\}

50

42

.\"

43

.\" Escape single quotes in literal strings from groff's Unicode transform.

44

.ie \n(.g .ds Aq \(aq

45

.el .ds Aq '

46

.\"

51

47

.\" If the F register is turned on, we'll generate index entries on stderr for

52

.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index

48

.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index

53

49

.\" entries marked with X<> in POD. Of course, you'll have to process the

54

50

.\" output yourself in some meaningful fashion.

55

.if \nF \{\

51

.ie \nF \{\

56

52

. de IX

57

53

. tm Index:\\$1\t\\n%\t"\\$2"

58

54

..

59

55

. nr % 0

60

56

. rr F

61

57

.\}

62

.\"

63

.\" For nroff, turn off justification. Always turn off hyphenation; it makes

64

.\" way too many mistakes in technical documents.

65

.hy 0

66

.if n .na

58

.el \{\

59

. de IX

60

..

61

.\}

67

62

.\"

68

63

.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).

69

64

.\" Fear. Run. Save yourself. No user-serviceable parts.

129

124

.\" ========================================================================

130

125

.\"

131

126

.IX Title "keychain 1"

132

.TH keychain 1 "2006-09-08" "2.6.8" "http://gentoo.org/proj/en/keychain.xml"

127

.TH keychain 1 "2010-05-07" "2.7.1" "http://www.funtoo.org"

128

.\" For nroff, turn off justification. Always turn off hyphenation; it makes

129

.\" way too many mistakes in technical documents.

130

.if n .ad l

131

.nh

133

132

.SH "NAME"

134

133

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

135

134

.SH "SYNOPSIS"

141

140

[\ \-\-stop\ \fIwhich\fR\ ]\ [\ \-\-timeout\ \fIminutes\fR\ ]\ [\ keys...\ ]

142

141

.SH "DESCRIPTION"

143

142

.IX Header "DESCRIPTION"

144

keychain is a manager for ssh\-agent, typically run from

143

keychain is a manager for ssh-agent, typically run from

145

144

~/.bash_profile. It allows your shells and cron jobs to share a

146

145

single ssh-agent process. By default, the ssh-agent started by

147

146

keychain is long-running and will continue to run, even after you have

148

147

logged out from the system. If you want to change this behavior, take

149

148

a look at the \-\-clear and \-\-timeout options, described below.

150

149

.PP

151

When keychain is run, it checks for a running ssh\-agent, otherwise it

150

When keychain is run, it checks for a running ssh-agent, otherwise it

152

151

starts one. It saves the ssh-agent environment variables to

153

152

~/.keychain/${\s-1HOSTNAME\s0}\-sh, so that subsequent logins and

154

153

non-interactive shells such as cron jobs can source the file and make

155

154

passwordless ssh connections. In addition, when keychain runs, it

156

155

verifies that the key files specified on the command-line are known to

157

ssh\-agent, otherwise it loads them, prompting you for a password if

156

ssh-agent, otherwise it loads them, prompting you for a password if

158

157

necessary.

159

158

.PP

160

159

Keychain also supports gpg-agent in the same ways that ssh-agent is

164

163

option.

165

164

.PP

166

165

keychain supports most UNIX-like operating systems, including Cygwin.

167

It works with Bourne\-compatible, csh-compatible and fish shells.

166

It works with Bourne-compatible, csh-compatible and fish shells.

168

167

.SH "OPTIONS"

169

168

.IX Header "OPTIONS"

170

169

.IP "\fB\-\-agents\fR \fIlist\fR" 4

171

170

.IX Item "--agents list"

172

171

Start the agents listed. By default keychain will build the list

173

172

automatically based on the existence of ssh-agent and/or gpg-agent on

174

the system. The list should be comma\-separated, for example \*(L"gpg,ssh\*(R"

173

the system. The list should be comma-separated, for example \*(L"gpg,ssh\*(R"

175

174

.IP "\fB\-\-attempts\fR \fInum\fR" 4

176

175

.IX Item "--attempts num"

177

176

Try num times to add keys before giving up. The default is 1.

178

177

.IP "\fB\-\-clear\fR" 4

179

178

.IX Item "--clear"

180

Delete all of ssh\-agent's keys. Typically this is used in

179

Delete all of ssh-agent's keys. Typically this is used in

181

180

\&.bash_profile. The theory behind this is that keychain should assume

182

181

that you are an intruder until proven otherwise. However, while this

183

182

option increases security, it still allows your cron jobs to use your

205

204

a non-standard place.

206

205

.IP "\fB\-h \-\-help\fR" 4

207

206

.IX Item "-h --help"

208

Show help that looks remarkably like this man\-page.

207

Show help that looks remarkably like this man-page. As of 2.6.10,

208

help is sent to stdout so it can be easily piped to a pager.

209

.IP "\fB\-\-host\fR \fIname\fR" 4

210

.IX Item "--host name"

211

Set alternate hostname for creation of pidfiles

240

.RS 4

241

.Sp

242

By default, keychain\-2.5.0 and later will behave as if \*(L"\-\-inherit

243

local\-once\*(R" is specified. You should specify \*(L"\-\-noinherit\*(R" if you

243

local-once\*(R" is specified. You should specify \*(L"\-\-noinherit\*(R" if you

244

want the older behavior.

245

.RE

246

.IP "\fB\-\-lockwait\fR \fIseconds\fR" 4

247

.IX Item "--lockwait seconds"

248

How long to wait for the lock to become available. Defaults to 30

249

seconds. \-1 indicates to wait forever.

248

How long to wait for the lock to become available. Defaults to 5

249

seconds. Specify a value of zero or more. If the lock cannot be

250

acquired within the specified number of seconds, then this keychain

251

process will forcefully acquire the lock.

250

252

.IP "\fB\-\-noask\fR" 4

251

253

.IX Item "--noask"

252

254

This option tells keychain do everything it normally does (ensure

253

255

ssh-agent is running, set up the ~/.keychain/[hostname]\-{c}sh files)

254

256

except that it will not prompt you to add any of the keys you

255

specified if they haven't yet been added to ssh\-agent.

257

specified if they haven't yet been added to ssh-agent.

256

258

.IP "\fB\-\-nocolor\fR" 4

257

259

.IX Item "--nocolor"

258

260

Disable color hilighting for non ANSI-compatible terms.

263

265

.IP "\fB\-\-noinherit\fR" 4

264

266

.IX Item "--noinherit"

265

267

Don't inherit any agent processes, overriding the default

266

\&\*(L"\-\-inherit local\-once\*(R"

268

\&\*(L"\-\-inherit local-once\*(R"

267

269

.IP "\fB\-\-nolock\fR" 4

268

270

.IX Item "--nolock"

269

271

Don't attempt to use a lockfile while manipulating files, pids and

291

293

.IP "\fB\-Q \-\-quick\fR" 4

292

294

.IX Item "-Q --quick"

293

295

If an ssh-agent process is running then use it. Don't verify the list

294

of keys, other than making sure it's non\-empty. This option avoids

296

of keys, other than making sure it's non-empty. This option avoids

295

297

locking when possible so that multiple terminals can be opened

296

298

simultaneously without waiting on each other.

297

299

.IP "\fB\-q \-\-quiet\fR" 4

298

300

.IX Item "-q --quiet"

299

Only print messages in case of warning, error or required

300

interactivity.

301

Only print messages in case of warning, error or required interactivity. As of

302

version 2.6.10, this also suppresses \*(L"Identities added\*(R" messages for ssh-agent.

301

303

.IP "\fB\-\-timeout\fR \fIminutes\fR" 4

302

304

.IX Item "--timeout minutes"

303

305

Set a timeout in minutes on your keys. This is conveyed to ssh-agent

312

314

key:

313

315

.PP

314

316

.Vb 1

315

\& eval `keychain --eval id_rsa id_dsa 0123ABCD`

317

\& eval \`keychain \-\-eval id_rsa id_dsa 0123ABCD\`

316

318

.Ve

317

319

.PP

318

320

If you have trouble with that in csh:

319

321

.PP

320

322

.Vb 2

321

323

\& setenv SHELL /bin/csh

322

\& eval `keychain --eval id_rsa id_dsa 0123ABCD`

324

\& eval \`keychain \-\-eval id_rsa id_dsa 0123ABCD\`

323

325

.Ve

324

326

.PP

325

327

This is equivalent for Bourne shells (including bash and zsh) but

327

329

.PP

328

330

.Vb 6

329

331

\& keychain id_rsa id_dsa 0123ABCD

330

\& [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`

331

\& [ -f $HOME/.keychain/$HOSTNAME-sh ] &&

332

\& . $HOME/.keychain/$HOSTNAME-sh

333

\& [ -f $HOME/.keychain/$HOSTNAME-sh-gpg ] &&

334

\& . $HOME/.keychain/$HOSTNAME-sh-gpg

332

\& [ \-z "$HOSTNAME" ] && HOSTNAME=\`uname \-n\`

333

\& [ \-f $HOME/.keychain/$HOSTNAME\-sh ] && \e

334

\& . $HOME/.keychain/$HOSTNAME\-sh

335

\& [ \-f $HOME/.keychain/$HOSTNAME\-sh\-gpg ] && \e

336

\& . $HOME/.keychain/$HOSTNAME\-sh\-gpg

335

337

.Ve

336

338

.PP

337

339

This is equivalent for C shell (including tcsh):

338

340

.PP

339

341

.Vb 8

340

342

\& keychain id_rsa id_dsa 0123ABCD

341

\& host=`uname -n`

342

\& if (-f $HOME/.keychain/$host-csh) then

343

\& source $HOME/.keychain/$host-csh

343

\& host=\`uname \-n\`

344

\& if (\-f $HOME/.keychain/$host\-csh) then

345

\& source $HOME/.keychain/$host\-csh

344

346

\& endif

345

\& if (-f $HOME/.keychain/$host-csh-gpg) then

346

\& source $HOME/.keychain/$host-csh-gpg

347

\& if (\-f $HOME/.keychain/$host\-csh\-gpg) then

348

\& source $HOME/.keychain/$host\-csh\-gpg

347

349

\& endif

348

350

.Ve

349

351

.PP

352

354

.PP

353

355

.Vb 4

354

356

\& # Load keychain variables and check for id_dsa

355

\& [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`

356

\& . $HOME/.keychain/$HOSTNAME-sh 2>/dev/null

357

\& ssh-add -l 2>/dev/null | grep -q id_dsa || exit 1

357

\& [ \-z "$HOSTNAME" ] && HOSTNAME=\`uname \-n\`

358

\& . $HOME/.keychain/$HOSTNAME\-sh 2>/dev/null

359

\& ssh\-add \-l 2>/dev/null | grep \-q id_dsa || exit 1

358

360

.Ve

359

361

.SH "SEE ALSO"

360

362

.IX Header "SEE ALSO"

361

363

\&\fIssh\-agent\fR\|(1)

362

364

.SH "NOTES"

363

365

.IX Header "NOTES"

364

Keychain is maintained by Aron Griffis <agriffis@gentoo.org>. If you

365

need to report a bug or request an enhancement, please do so at

366

<http://bugs.gentoo.org/> and assign to agriffis@gentoo.org

367

.PP

368

Keychain was originally written by Daniel Robbins

369

<drobbins@gentoo.org>, who has also written a series of three articles

370

about it. The articles can be found starting at

371

<http://www\-106.ibm.com/developerworks/library/l\-keyc.html>

366

Keychain was created and is currently maintained by Daniel Robbins. If you need

367

to report a bug or request an enhancement, please post to the funtoo-dev

368

mailing list <http://groups.google.com/group/funtoo\-dev>. For more information

369

about keychain, please visit <http://www.funtoo.org>.