/mandos/release : revision 138

3

"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

4

<!ENTITY VERSION "1.0">

5

<!ENTITY COMMANDNAME "plugin-runner">

6

<!ENTITY TIMESTAMP "2008-08-31">

6

<!ENTITY TIMESTAMP "2008-09-01">

7

]>

8

9

9

10

11

<title>Mandos Manual</title>

12

34

<holder>Teddy Hogeborn</holder>

35

<holder>Björn Påhlsson</holder>

36

</copyright>

37

38

<para>

39

This manual page is free software: you can redistribute it

40

and/or modify it under the terms of the GNU General Public

41

License as published by the Free Software Foundation,

42

either version 3 of the License, or (at your option) any

43

later version.

44

</para>

45

46

<para>

47

This manual page is distributed in the hope that it will

48

be useful, but WITHOUT ANY WARRANTY; without even the

49

implied warranty of MERCHANTABILITY or FITNESS FOR A

50

PARTICULAR PURPOSE. See the GNU General Public License

51

for more details.

52

</para>

53

54

<para>

55

You should have received a copy of the GNU General Public

56

License along with this program; If not, see

57

<ulink url="http://www.gnu.org/licenses/"/>.

58

</para>

59

</legalnotice>

37

<xi:include href="legalnotice.xml"/>

60

38

</refentryinfo>

61

39

62

40

75

53

76

54

<command>&COMMANDNAME;</command>

77

55

78

<arg choice="plain"><option>--global-envs=<replaceable

56

<arg choice="plain"><option>--global-env=<replaceable

79

57

>VAR</replaceable><literal>=</literal><replaceable

80

58

>value</replaceable></option></arg>

81

59

<arg choice="plain"><option>-e

84

62

</group>

85

63

<sbr/>

86

64

87

<arg choice="plain"><option>--envs-for=<replaceable

65

<arg choice="plain"><option>--env-for=<replaceable

88

66

>PLUGIN</replaceable><literal>:</literal><replaceable

89

67

>ENV</replaceable><literal>=</literal><replaceable

90

68

>value</replaceable></option></arg>

147

125

</group>

148

126

</cmdsynopsis>

149

127

</refsynopsisdiv>

150

128

151

129

152

130

<title>DESCRIPTION</title>

153

131

<para>

154

<command>&COMMANDNAME;</command> is a plugin runner that waits

155

for any of its plugins to return sucessfull with a password, and

156

passes it to cryptsetup as stdout message. This command is not

157

meant to be invoked directly, but is instead meant to be run by

158

cryptsetup by being specified in /etc/crypttab as a keyscript

159

and subsequlently started in the initrd environment. See

160

<citerefentry><refentrytitle>crypttab</refentrytitle>

161

<manvolnum>5</manvolnum></citerefentry> for more information on

162

keyscripts.

163

</para>

164

165

<para>

166

plugins is looked for in the plugins directory which by default will be

167

/conf/conf.d/mandos/plugins.d if not changed by option --plugin-dir.

168

</para>

169

</refsect1>

132

<command>&COMMANDNAME;</command> is a program which is meant to

133

be specified as <quote>keyscript</quote> in <citerefentry>

134

<refentrytitle>crypttab</refentrytitle>

135

<manvolnum>5</manvolnum></citerefentry> for the root disk. The

136

aim of this program is therefore to output a password, which

137

then <citerefentry><refentrytitle>cryptsetup</refentrytitle>

138

<manvolnum>8</manvolnum></citerefentry> will use to try and

139

unlock the root disk.

140

</para>

141

<para>

142

This program is not meant to be invoked directly, but can be in

143

order to test it. Note that any password obtained will simply

144

be output on standard output.

145

</para>

146

</refsect1>

147

148

149

<title>PURPOSE</title>

150

<para>

151

The purpose of this is to enable <emphasis>remote and unattended

152

rebooting</emphasis> of client host computer with an

153

<emphasis>encrypted root file system</emphasis>. See <xref

154

linkend="overview"/> for details.

155

</para>

156

</refsect1>

157

170

158

171

159

<title>OPTIONS</title>

172

160

173

161

162

<term><option>--global-env

163

<replaceable>VAR</replaceable><literal>=</literal><replaceable

164

>value</replaceable></option></term>

165

<term><option>-e

166

<replaceable>VAR</replaceable><literal>=</literal><replaceable

167

>value</replaceable></option></term>

168

169

<para>

170

This option will add an environment variable setting to

171

all plugins. This will override any inherited environment

172

variable.

173

</para>

174

</listitem>

175

</varlistentry>

176

177

178

<term><option>--env-for

179

<replaceable>PLUGIN</replaceable><literal>:</literal

180

><replaceable>ENV</replaceable><literal>=</literal

181

><replaceable>value</replaceable></option></term>

182

<term><option>-f

183

<replaceable>PLUGIN</replaceable><literal>:</literal

184

><replaceable>ENV</replaceable><literal>=</literal

185

><replaceable>value</replaceable></option></term>

186

187

<para>

188

This option will add an environment variable setting to

189

the <replaceable>PLUGIN</replaceable> plugin. This will

190

override any inherited environment variables or

191

environment variables specified using

192

<option>--global-env</option>.

193

</para>

194

</listitem>

195

</varlistentry>

196

197

174

198

<term><option>--global-options

175

199

<replaceable>OPTIONS</replaceable></option></term>

176

200

<term><option>-g

177

201

<replaceable>OPTIONS</replaceable></option></term>

178

202

179

203

<para>

180

Global options given to all plugins as additional start

181

arguments. Options are specified with a -o flag followed

182

by a comma separated string of options.

183

</para>

204

Pass some options to <emphasis>all</emphasis> plugins.

205

<replaceable>OPTIONS</replaceable> is a comma separated

206

list of options. This is not a very useful option, except

207

for specifying the <quote><option>--debug</option></quote>

208

for all plugins.

209

</para>

184

210

</listitem>

185

211

</varlistentry>

186

212

187

213

188

214

<term><option>--options-for

189

215

<replaceable>PLUGIN</replaceable><literal>:</literal

193

219

><replaceable>OPTION</replaceable></option></term>

194

220

195

221

<para>

196

Plugin specific options given to the plugin as additional

197

start arguments. Options are specified with a -o flag

198

followed by a comma separated string of options.

199

</para>

222

Pass some options to a specific plugin. <replaceable

223

>PLUGIN</replaceable> is the name (file basename) of a

224

plugin, and <replaceable>OPTIONS</replaceable> is a comma

225

separated list of options.

226

</para>

227

<para>

228

Note that since options are not split on whitespace, the

229

way to pass, to the plugin

230

<quote><filename>foo</filename></quote>, the option

231

<option>--bar</option> with the option argument

232

<quote>baz</quote> is either

233

<userinput>--options-for=foo:--bar=baz</userinput> or

234

<userinput>--options-for=foo:--bar,baz</userinput>, but

235

236

<userinput>--options-for="foo:--bar baz"</userinput>.

237

</para>

200

238

</listitem>

201

239

</varlistentry>

202

240

207

245

<replaceable>PLUGIN</replaceable></option></term>

208

246

209

247

<para>

210

Disable a specific plugin

248

Disable the plugin named

249

<replaceable>PLUGIN</replaceable>. The plugin will not be

250

started.

211

251

</para>

212

252

</listitem>

213

253

</varlistentry>

217

257

218

258

219

259

<para>

220

Group ID the plugins will run as

260

Change to group ID <replaceable>ID</replaceable> on

261

startup. The default is 65534. All plugins will be

262

started using this group ID. <emphasis>Note:</emphasis>

263

This must be a number, not a name.

221

264

</para>

222

265

</listitem>

223

266

</varlistentry>

227

270

228

271

229

272

<para>

230

User ID the plugins will run as

273

Change to user ID <replaceable>ID</replaceable> on

274

startup. The default is 65534. All plugins will be

275

started using this user ID. <emphasis>Note:</emphasis>

276

This must be a number, not a name.

231

277

</para>

232

278

</listitem>

233

279

</varlistentry>

237

283

<replaceable>DIRECTORY</replaceable></option></term>

238

284

239

285

<para>

240

Specify a different plugin directory

286

Specify a different plugin directory. The default is

287

<filename>/lib/mandos/plugins.d</filename>, which will

288

exist in the initial <acronym>RAM</acronym> disk

289

environment.

241

290

</para>

242

291

</listitem>

243

292

</varlistentry>

246

295

<term><option>--debug</option></term>

247

296

248

297

<para>

249

Debug mode

298

Enable debug mode. This will enable a lot of output to

299

standard error about what the program is doing. The

300

program will still perform all other functions normally.

301

The default is to <emphasis>not</emphasis> run in debug

302

mode.

303

</para>

304

<para>

305

The plugins will <emphasis>not</emphasis> be affected by

306

this option. Use

307

<userinput><option>--global-options=--debug</option></userinput>

308

if complete debugging eruption is desired.

250

309

</para>

251

310

</listitem>

252

311

</varlistentry>

256

315

257

316

258

317

<para>

259

Gives a help message

318

Gives a help message about options and their meanings.

260

319

</para>

261

320

</listitem>

262

321

</varlistentry>

265

324

<term><option>--usage</option></term>

266

325

267

326

<para>

268

Gives a short usage message

327

Gives a short usage message.

269

328

</para>

270

329

</listitem>

271

330

</varlistentry>

275

334

276

335

277

336

<para>

278

Prints the program version

337

Prints the program version.

279

338

</para>

280

339

</listitem>

281

340

</varlistentry>

282

341

</variablelist>

283

342

</refsect1>

284

343

344

345

<title>OVERVIEW</title>

346

<xi:include href="overview.xml"/>

347

<para>

348

This program will run on the client side in the initial

349

<acronym>RAM</acronym> disk environment, and is responsible for

350

getting a password. It does this by running plugins, one of

351

which will normally be the actual client program communicating

352

with the server.

353

</para>

354

</refsect1>

355

356

<title>PLUGINS</title>

357

<para>

358

This program will get a password by running a number of

359

<firstterm>plugins</firstterm>, which are simply executable

360

programs in a directory in the initial <acronym>RAM</acronym>

361

disk environment. The default directory is

362

<filename>/lib/mandos/plugins.d</filename>, but this can be

363

changed with the <option>--plugin-dir</option> option. The

364

plugins are started in parallel, and the first plugin to output

365

a password <emphasis>and</emphasis> exit with a successful exit

366

code will make this plugin-runner output the password from that

367

plugin, stop any other plugins, and exit.

368

</para>

369

</refsect1>

370

371

372

<title>FALLBACK</title>

373

<para>

374

If no plugins succeed, this program will, as a fallback, ask for

375

a password on the console using <citerefentry><refentrytitle

376

>getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

377

and output it. This is not meant to be the normal mode of

378

operation, as there is a separate plugin for getting a password

379

from the console.

380

</para>

381

</refsect1>

382

285

383

286

384

<title>EXIT STATUS</title>

287

385

<para>

288

</para>

289

</refsect1>

290

386

Exit status of this program is zero if no errors were

387

encountered, and otherwise not. The fallback (see <xref

388

linkend="fallback"/>) may or may not have succeeded in either

389

case.

390

</para>

391

</refsect1>

392

393

394

<title>ENVIRONMENT</title>

395

<para>

396

397

</para>

398

</refsect1>

399

291

400

292

401

<title>FILES</title>

293

402

<para>

294

</para>

295

</refsect1>

296

297

298

<title>NOTES</title>

299

<para>

403

404

405

<term><filename

406

>/conf/conf.d/mandos/plugin-runner.conf</filename></term>

407

408

<para>

409

Since this program will be run as a keyscript, there is

410

little to no opportunity to pass command line arguments

411

to it. Therefore, it will <emphasis>also</emphasis>

412

read this file and use its contents as

413

whitespace-separated command line options. Also,

414

everything from a <quote>#</quote> character to the end

415

of a line is ignored.

416

</para>

417

<para>

418

This file will be processed <emphasis>before</emphasis>

419

the normal command line options, so the latter can

420

override the former, if need be.

421

</para>

422

</listitem>

423

</varlistentry>

424

</variablelist>

300

425

</para>

301

426

</refsect1>

302

427

303

428

304

429

305

430

<para>

431

There is no <option>--enable</option> option to enable disabled

432

plugins.

306

433

</para>

307

434

</refsect1>

308

435

309

436

310

437

<title>EXAMPLE</title>

311

438

<para>

312

439

</para>

313

440

</refsect1>

314

441

315

442

316

443

<title>SECURITY</title>

317

444

<para>

318

445

</para>

319

446

</refsect1>

320

447

321

448

322

449

323

450

<para>

331

458

<manvolnum>8mandos</manvolnum></citerefentry>

332

459

</para>

333

460

</refsect1>

334

461

335

462

</refentry>

336

463

337

464