/mandos/release : revision 165

To get this branch, use:

bzr branch
http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to plugin-runner.xml

Committer: Teddy Hogeborn
Date: 2008-09-05 18:37:28 UTC
Revision ID: teddy@fukt.bsnet.se-20080905183728-l0m8v3vqa302uwrw

* mandos (main): Use EAFP with pidfile.

Show diffs side-by-side

added added

removed removed

plugin-runner.xml

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

<!ENTITY VERSION "1.0">

<!ENTITY COMMANDNAME "plugin-runner">

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

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

<refname><command>&COMMANDNAME;</command></refname>

Run Mandos plugins. Pass data from first succesful one.

Run Mandos plugins, pass data from first to succeed.

</refpurpose>

</refnamediv>

<command>&COMMANDNAME;</command>

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

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

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

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

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

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

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

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

</group>

<sbr/>

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

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

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

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

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

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

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

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

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

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

>OPTIONS</replaceable></option></arg>

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

>OPTIONS</replaceable> </option></arg>

</group>

<replaceable>PLUGIN</replaceable> </option></arg>

</group>

<sbr/>

<arg choice="plain"><option>--enable=<replaceable

100

>PLUGIN</replaceable></option></arg>

101

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

102

<replaceable>PLUGIN</replaceable> </option></arg>

103

</group>

104

<sbr/>

105

<arg><option>--groupid=<replaceable

106

>ID</replaceable></option></arg>

100

107

<sbr/>

104

111

<arg><option>--plugin-dir=<replaceable

105

112

>DIRECTORY</replaceable></option></arg>

106

113

<sbr/>

114

<arg><option>--config-file=<replaceable

115

>FILE</replaceable></option></arg>

116

<sbr/>

107

117

<arg><option>--debug</option></arg>

108

118

</cmdsynopsis>

109

119

125

135

</group>

126

136

</cmdsynopsis>

127

137

</refsynopsisdiv>

128

138

129

139

130

140

<title>DESCRIPTION</title>

131

141

<para>

132

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

133

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

134

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

135

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

136

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

137

and subsequlently started in the initrd environment. See

142

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

143

be specified as a <quote>keyscript</quote> for the root disk in

138

144

<citerefentry><refentrytitle>crypttab</refentrytitle>

139

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

140

keyscripts.

141

</para>

142

143

<para>

144

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

145

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

146

</para>

147

</refsect1>

145

<manvolnum>5</manvolnum></citerefentry>. The aim of this

146

program is therefore to output a password, which then

147

<citerefentry><refentrytitle>cryptsetup</refentrytitle>

148

<manvolnum>8</manvolnum></citerefentry> will use to unlock the

149

root disk.

150

</para>

151

<para>

152

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

153

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

154

be output on standard output.

155

</para>

156

</refsect1>

157

158

159

<title>PURPOSE</title>

160

<para>

161

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

162

rebooting</emphasis> of client host computer with an

163

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

164

linkend="overview"/> for details.

165

</para>

166

</refsect1>

167

148

168

149

169

<title>OPTIONS</title>

150

170

151

171

172

<term><option>--global-env

173

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

174

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

175

<term><option>-G

176

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

177

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

178

179

<para>

180

This option will add an environment variable setting to

181

all plugins. This will override any inherited environment

182

variable.

183

</para>

184

</listitem>

185

</varlistentry>

186

187

188

<term><option>--env-for

189

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

190

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

191

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

192

<term><option>-E

193

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

194

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

195

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

196

197

<para>

198

This option will add an environment variable setting to

199

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

200

override any inherited environment variables or

201

environment variables specified using

202

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

203

</para>

204

</listitem>

205

</varlistentry>

206

207

152

208

<term><option>--global-options

153

209

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

154

210

<term><option>-g

155

211

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

156

212

157

213

<para>

158

Global options given to all plugins as additional start

159

arguments. Options are specified with a -o flag followed

160

by a comma separated string of options.

161

</para>

214

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

215

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

216

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

217

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

218

option to all plugins.

219

</para>

162

220

</listitem>

163

221

</varlistentry>

164

222

165

223

166

224

<term><option>--options-for

167

225

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

171

229

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

172

230

173

231

<para>

174

Plugin specific options given to the plugin as additional

175

start arguments. Options are specified with a -o flag

176

followed by a comma separated string of options.

177

</para>

232

Pass some options to a specific plugin. <replaceable

233

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

234

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

235

separated list of options.

236

</para>

237

<para>

238

Note that since options are not split on whitespace, the

239

way to pass, to the plugin

240

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

241

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

242

<quote>baz</quote> is either

243

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

244

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

245

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

246

<emphasis>not</emphasis> work.

247

</para>

178

248

</listitem>

179

249

</varlistentry>

180

250

181

251

182

<term><option> --disable

252

<term><option>--disable

183

253

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

184

254

<term><option>-d

185

255

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

186

256

187

257

<para>

188

Disable a specific plugin

258

Disable the plugin named

259

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

260

started.

189

261

</para>

190

262

</listitem>

191

263

</varlistentry>

192

264

193

265

266

<term><option>--enable

267

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

268

<term><option>-e

269

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

270

271

<para>

272

Re-enable the plugin named

273

<replaceable>PLUGIN</replaceable>. This is only useful to

274

undo a previous <option>--disable</option> option, maybe

275

from the configuration file.

276

</para>

277

</listitem>

278

</varlistentry>

279

280

194

281

<term><option>--groupid

195

282

196

283

197

284

<para>

198

Group ID the plugins will run as

285

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

286

startup. The default is 65534. All plugins will be

287

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

288

This must be a number, not a name.

199

289

</para>

200

290

</listitem>

201

291

</varlistentry>

205

295

206

296

207

297

<para>

208

User ID the plugins will run as

298

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

299

startup. The default is 65534. All plugins will be

300

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

301

This must be a number, not a name.

209

302

</para>

210

303

</listitem>

211

304

</varlistentry>

215

308

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

216

309

217

310

<para>

218

Specify a different plugin directory

311

Specify a different plugin directory. The default is

312

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

313

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

314

environment.

315

</para>

316

</listitem>

317

</varlistentry>

318

319

320

<term><option>--config-file

321

322

323

<para>

324

Specify a different file to read additional options from.

325

See <xref linkend="files"/>. Other command line options

326

will override options specified in the file.

219

327

</para>

220

328

</listitem>

221

329

</varlistentry>

224

332

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

225

333

226

334

<para>

227

Debug mode

335

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

336

standard error about what the program is doing. The

337

program will still perform all other functions normally.

338

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

339

mode.

340

</para>

341

<para>

342

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

343

this option. Use

344

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

345

if complete debugging eruption is desired.

228

346

</para>

229

347

</listitem>

230

348

</varlistentry>

234

352

235

353

236

354

<para>

237

Gives a help message

355

Gives a help message about options and their meanings.

238

356

</para>

239

357

</listitem>

240

358

</varlistentry>

243

361

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

244

362

245

363

<para>

246

Gives a short usage message

364

Gives a short usage message.

247

365

</para>

248

366

</listitem>

249

367

</varlistentry>

253

371

254

372

255

373

<para>

256

Prints the program version

374

Prints the program version.

257

375

</para>

258

376

</listitem>

259

377

</varlistentry>

260

378

</variablelist>

261

379

</refsect1>

262

380

381

382

<title>OVERVIEW</title>

383

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

384

<para>

385

This program will run on the client side in the initial

386

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

387

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

388

which will normally be the actual client program communicating

389

with the server.

390

</para>

391

</refsect1>

392

393

<title>PLUGINS</title>

394

<para>

395

This program will get a password by running a number of

396

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

397

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

398

disk environment. The default directory is

399

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

400

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

401

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

402

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

403

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

404

plugin, stop any other plugins, and exit.

405

</para>

406

407

408

<title>WRITING PLUGINS</title>

409

<para>

410

A plugin is simply a program which prints a password to its

411

standard output and then exits with a successful (zero) exit

412

status. If the exit status is not zero, any output on

413

standard output will be ignored by the plugin runner. Any

414

output on its standard error channel will simply be passed to

415

the standard error of the plugin runner, usually the system

416

console.

417

</para>

418

<para>

419

The plugin will run in the initial RAM disk environment, so

420

care must be taken not to depend on any files or running

421

services not available there.

422

</para>

423

<para>

424

The plugin must exit cleanly and free all allocated resources

425

upon getting the TERM signal, since this is what the plugin

426

runner uses to stop all other plugins when one plugin has

427

output a password and exited cleanly.

428

</para>

429

<para>

430

The plugin must not use resources, like for instance reading

431

from the standard input, without knowing that no other plugin

432

is also using it.

433

</para>

434

<para>

435

It is useful, but not required, for the plugin to take the

436

<option>--debug</option> option.

437

</para>

438

</refsect2>

439

</refsect1>

440

441

442

<title>FALLBACK</title>

443

<para>

444

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

445

a password on the console using <citerefentry><refentrytitle

446

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

447

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

448

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

449

from the console.

450

</para>

451

</refsect1>

452

263

453

264

454

<title>EXIT STATUS</title>

265

455

<para>

266

</para>

267

</refsect1>

268

269

456

Exit status of this program is zero if no errors were

457

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

458

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

459

case.

460

</para>

461

</refsect1>

462

463

464

<title>ENVIRONMENT</title>

465

<para>

466

This program does not use any environment variables itself, it

467

only passes on its environment to all the plugins. The

468

environment passed to plugins can be modified using the

469

<option>--global-env</option> and <option>--env-for</option>

470

options.

471

</para>

472

</refsect1>

473

474

270

475

<title>FILES</title>

271

476

<para>

272

</para>

273

</refsect1>

274

275

276

<title>NOTES</title>

277

<para>

477

478

479

<term><filename

480

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

481

482

<para>

483

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

484

little to no opportunity to pass command line arguments

485

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

486

read this file and use its contents as

487

whitespace-separated command line options. Also,

488

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

489

of a line is ignored.

490

</para>

491

<para>

492

This program is meant to run in the initial RAM disk

493

environment, so that is where this file is assumed to

494

exist. The file does not need to exist in the normal

495

file system.

496

</para>

497

<para>

498

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

499

the normal command line options, so the latter can

500

override the former, if need be.

501

</para>

502

<para>

503

This file name is the default; the file to read for

504

arguments can be changed using the

505

<option>--config-file</option> option.

506

</para>

507

</listitem>

508

</varlistentry>

509

</variablelist>

278

510

</para>

279

511

</refsect1>

280

512

281

513

282

514

283

515

<para>

516

The <option>--config-file</option> option is ignored when

517

specified from within a configuration file.

284

518

</para>

285

519

</refsect1>

286

520

287

521

288

522

<title>EXAMPLE</title>

289

<para>

290

</para>

523

524

<para>

525

Normal invocation needs no options:

526

</para>

527

<para>

528

<userinput>&COMMANDNAME;</userinput>

529

</para>

530

</informalexample>

531

532

<para>

533

Run the program, but not the plugins, in debug mode:

534

</para>

535

<para>

536

537

538

<userinput>&COMMANDNAME; --debug</userinput>

539

540

</para>

541

</informalexample>

542

543

<para>

544

Run all plugins, but run the <quote>foo</quote> plugin in

545

debug mode:

546

</para>

547

<para>

548

549

550

<userinput>&COMMANDNAME; --options-for=foo:--debug</userinput>

551

552

</para>

553

</informalexample>

554

555

<para>

556

Run all plugins, but not the program, in debug mode:

557

</para>

558

<para>

559

560

561

<userinput>&COMMANDNAME; --global-options=--debug</userinput>

562

563

</para>

564

</informalexample>

565

566

<para>

567

Run plugins from a different directory, read a different

568

configuration file, and add two options to the

569

<citerefentry><refentrytitle >password-request</refentrytitle>

570

<manvolnum>8mandos</manvolnum></citerefentry> plugin:

571

</para>

572

<para>

573

574

575

<userinput>&COMMANDNAME; --config-file=/etc/mandos/plugin-runner.conf --plugin-dir /usr/lib/mandos/plugins.d --options-for=password-request:--pubkey=/etc/keys/mandos/pubkey.txt,--seckey=/etc/keys/mandos/seckey.txt</userinput>

576

577

</para>

578

</informalexample>

291

579

</refsect1>

292

293

580

294

581

<title>SECURITY</title>

295

582

<para>

583

This program will, when starting, try to switch to another user.

584

If it is started as root, it will succeed, and will by default

585

switch to user and group 65534, which are assumed to be

586

non-privileged. This user and group is then what all plugins

587

will be started as. Therefore, the only way to run a plugin as

588

a privileged user is to have the set-user-ID or set-group-ID bit

589

set on the plugin executable file (see <citerefentry>

590

<refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>

591

</citerefentry>).

592

</para>

593

<para>

594

If this program is used as a keyscript in <citerefentry

595

><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>

596

</citerefentry>, there is a slight risk that if this program

597

fails to work, there might be no way to boot the system except

598

for booting from another media and editing the initial RAM disk

599

image to not run this program. This is, however, unlikely,

600

since the <citerefentry><refentrytitle

601

>password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>

602

</citerefentry> plugin will read a password from the console in

603

case of failure of the other plugins, and this plugin runner

604

will also, in case of catastrophic failure, itself fall back to

605

asking and outputting a password on the console (see <xref

606

linkend="fallback"/>).

296

607

</para>

297

608

</refsect1>

298

609

299

610

300

611

301

612

<para>

302

613

<citerefentry><refentrytitle>cryptsetup</refentrytitle>

303

614

<manvolnum>8</manvolnum></citerefentry>,

615

<citerefentry><refentrytitle>crypttab</refentrytitle>

616

<manvolnum>5</manvolnum></citerefentry>,

617

<citerefentry><refentrytitle>execve</refentrytitle>

618

<manvolnum>2</manvolnum></citerefentry>,

304

619

<citerefentry><refentrytitle>mandos</refentrytitle>

305

620

<manvolnum>8</manvolnum></citerefentry>,

306

621

<citerefentry><refentrytitle>password-prompt</refentrytitle>

309

624

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

310

625

</para>

311

626

</refsect1>

312

627

313

628

</refentry>

314

629

315

630

Older »