/mandos/release : revision 144

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-03 05:08:24 UTC
Revision ID: teddy@fukt.bsnet.se-20080903050824-x38ghzu01vkfrpb4

* plugins.d/password-request.xml (OVERVIEW): Improved wording.
(EXIT STATUS): Fixed typos.

files modified:
Makefile

TODO

mandos-options.xml

mandos.xml

plugin-runner.xml

plugins.d/password-request.c

plugins.d/password-request.xml

Show diffs side-by-side

added added

removed removed

plugin-runner.xml

145

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

146

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

147

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

148

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

149

unlock the root disk.

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

172

<term><option>--global-env

173

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

174

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

175

<term><option>-e

175

<term><option>-G

176

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

177

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

178

189

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

190

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

191

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

192

<term><option>-f

192

<term><option>-E

193

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

194

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

195

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

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

for all plugins.

218

option to all plugins.

219

</para>

220

</listitem>

221

</varlistentry>

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>, but

245

246

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

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>

248

</listitem>

249

</varlistentry>

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 plugins

432

are 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>

406

439

</refsect1>

407

440

408

441

477

510

</para>

478

511

</refsect1>

479

512

480

481

482

<para>

483

</para>

484

</refsect1>

513

514

515

516

517

485

518

486

519

487

520

<title>EXAMPLE</title>

488

<para>

489

</para>

521

522

<para>

523

Normal invocation needs no options:

524

</para>

525

<para>

526

<userinput>&COMMANDNAME;</userinput>

527

</para>

528

</informalexample>

529

530

<para>

531

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

532

</para>

533

<para>

534

535

536

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

537

538

</para>

539

</informalexample>

540

541

<para>

542

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

543

debug mode:

544

</para>

545

<para>

546

547

548

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

549

550

</para>

551

</informalexample>

552

553

<para>

554

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

555

</para>

556

<para>

557

558

559

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

560

561

</para>

562

</informalexample>

563

564

<para>

565

Run plugins from a different directory and add a special

566

option to the <citerefentry><refentrytitle

567

>password-request</refentrytitle>

568

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

569

</para>

570

<para>

571

572

573

<userinput>&COMMANDNAME; --plugin-dir=plugins.d --options-for=password-request:--keydir=keydir</userinput>

574

575

</para>

576

</informalexample>

490

577

</refsect1>

491

492

578

493

579

<title>SECURITY</title>

494

580

<para>

581

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

582

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

583

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

584

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

585

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

586

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

587

set on the plugin executable files (see <citerefentry>

588

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

589

</citerefentry>).

590

</para>

591

<para>

592

If this program is used as a keyscript in <citerefentry

593

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

594

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

595

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

596

booting from another media and editing the initial RAM disk

597

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

598

since the <citerefentry><refentrytitle

599

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

600

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

601

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

602

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

603

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

604

linkend="fallback"/>).

495

605

</para>

496

606

</refsect1>

497

607

500

610

<para>

501

611

<citerefentry><refentrytitle>cryptsetup</refentrytitle>

502

612

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

613

<citerefentry><refentrytitle>crypttab</refentrytitle>

614

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

615

<citerefentry><refentrytitle>execve</refentrytitle>

616

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

503

617

<citerefentry><refentrytitle>mandos</refentrytitle>

504

618

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

505

619

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

Older »