/mandos/release : revision 24.1.86

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-09-01">

6

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

7

]>

8

9

56

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

57

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

58

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

59

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

59

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

60

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

61

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

62

</group>

66

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

67

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

68

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

69

69

70

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

71

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

72

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

83

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

84

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

85

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

86

86

87

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

88

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

89

</group>

95

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

96

</group>

97

<sbr/>

98

99

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

98

105

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

99

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

135

145

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

136

146

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

137

147

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

138

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

139

unlock the root disk.

148

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

149

root disk.

140

150

</para>

141

151

<para>

142

152

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

162

172

<term><option>--global-env

163

173

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

164

174

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

165

<term><option>-e

175

<term><option>-G

166

176

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

167

177

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

168

178

179

189

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

180

190

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

181

191

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

182

<term><option>-f

192

<term><option>-E

183

193

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

184

194

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

185

195

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

205

215

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

206

216

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

207

217

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

208

for all plugins.

218

option to all plugins.

209

219

</para>

210

220

</listitem>

211

221

</varlistentry>

231

241

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

232

242

<quote>baz</quote> is either

233

243

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

244

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

245

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

246

<emphasis>not</emphasis> work.

237

247

</para>

238

248

</listitem>

239

249

</varlistentry>

240

250

241

251

242

<term><option> --disable

252

<term><option>--disable

243

253

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

244

254

<term><option>-d

245

255

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

253

263

</varlistentry>

254

264

255

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 config file.

276

</para>

277

</listitem>

278

</varlistentry>

279

280

256

281

<term><option>--groupid

257

282

258

283

292

317

</varlistentry>

293

318

294

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.

327

</para>

328

</listitem>

329

</varlistentry>

330

331

295

332

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

296

333

297

334

<para>

366

403

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

367

404

plugin, stop any other plugins, and exit.

368

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>

369

439

</refsect1>

370

440

371

441

393

463

394

464

<title>ENVIRONMENT</title>

395

465

<para>

396

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

optins.

397

471

</para>

398

472

</refsect1>

399

473

400

474

401

475

<title>FILES</title>

402

476

<para>

403

477

415

489

of a line is ignored.

416

490

</para>

417

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>

418

498

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

419

499

the normal command line options, so the latter can

420

500

override the former, if need be.

421

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>

422

507

</listitem>

423

508

</varlistentry>

424

509

</variablelist>

425

510

</para>

426

511

</refsect1>

427

512

428

429

430

<para>

431

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

432

plugins.

433

</para>

434

</refsect1>

513

514

515

516

517

435

518

436

519

437

520

<title>EXAMPLE</title>

438

<para>

439

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

440

577

</refsect1>

441

442

578

443

579

<title>SECURITY</title>

444

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"/>).

445

605

</para>

446

606

</refsect1>

447

607

450

610

<para>

451

611

<citerefentry><refentrytitle>cryptsetup</refentrytitle>

452

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

453

617

<citerefentry><refentrytitle>mandos</refentrytitle>

454

618

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

455

619

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