/mandos/trunk : revision 170

1

<?xml version="1.0" encoding="UTF-8"?>

2

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

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-06">

7

]>

8

9

10

11

<title>Mandos Manual</title>

12

13

<productname>Mandos</productname>

14

<productnumber>&VERSION;</productnumber>

15

<date>&TIMESTAMP;</date>

16

17

18

<firstname>Björn</firstname>

19

<surname>Påhlsson</surname>

20

21

<email>belorn@fukt.bsnet.se</email>

22

</address>

23

</author>

24

25

<firstname>Teddy</firstname>

26

<surname>Hogeborn</surname>

27

28

<email>teddy@fukt.bsnet.se</email>

29

</address>

30

</author>

31

</authorgroup>

32

33

34

<holder>Teddy Hogeborn</holder>

35

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

36

</copyright>

37

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

38

</refentryinfo>

39

40

41

<refentrytitle>&COMMANDNAME;</refentrytitle>

42

<manvolnum>8mandos</manvolnum>

43

</refmeta>

44

45

46

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

47

48

Run Mandos plugins, pass data from first to succeed.

49

</refpurpose>

50

</refnamediv>

51

52

53

54

<command>&COMMANDNAME;</command>

55

56

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

57

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

58

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

59

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

60

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

61

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

62

</group>

63

<sbr/>

64

65

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

66

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

67

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

68

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

69

70

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

71

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

72

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

73

</group>

74

<sbr/>

75

76

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

77

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

78

79

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

80

</group>

81

<sbr/>

82

83

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

84

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

85

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

86

87

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

88

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

89

</group>

90

<sbr/>

91

92

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

93

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

94

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

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

105

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

106

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

107

<sbr/>

108

<arg><option>--userid=<replaceable

109

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

110

<sbr/>

111

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

112

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

113

<sbr/>

114

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

115

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

116

<sbr/>

117

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

118

</cmdsynopsis>

119

120

<command>&COMMANDNAME;</command>

121

122

123

124

</group>

125

</cmdsynopsis>

126

127

<command>&COMMANDNAME;</command>

128

<arg choice="plain"><option>--usage</option></arg>

129

</cmdsynopsis>

130

131

<command>&COMMANDNAME;</command>

132

133

<arg choice="plain"><option>--version</option></arg>

134

135

</group>

136

</cmdsynopsis>

137

</refsynopsisdiv>

138

139

140

<title>DESCRIPTION</title>

141

<para>

142

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

143

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

144

<citerefentry><refentrytitle>crypttab</refentrytitle>

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

168

169

<title>OPTIONS</title>

170

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

208

<term><option>--global-options

209

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

210

<term><option>-g

211

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

212

213

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

220

</listitem>

221

</varlistentry>

222

223

224

<term><option>--options-for

225

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

226

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

227

<term><option>-o

228

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

229

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

230

231

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

248

</listitem>

249

</varlistentry>

250

251

252

<term><option>--disable

253

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

254

<term><option>-d

255

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

256

257

<para>

258

Disable the plugin named

259

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

260

started.

261

</para>

262

</listitem>

263

</varlistentry>

264

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

281

<term><option>--groupid

282

283

284

<para>

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.

289

</para>

290

</listitem>

291

</varlistentry>

292

293

294

<term><option>--userid

295

296

297

<para>

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.

302

</para>

303

</listitem>

304

</varlistentry>

305

306

307

<term><option>--plugin-dir

308

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

309

310

<para>

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.

327

</para>

328

</listitem>

329

</varlistentry>

330

331

332

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

333

334

<para>

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.

346

</para>

347

</listitem>

348

</varlistentry>

349

350

351

352

353

354

<para>

355

Gives a help message about options and their meanings.

356

</para>

357

</listitem>

358

</varlistentry>

359

360

361

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

362

363

<para>

364

Gives a short usage message.

365

</para>

366

</listitem>

367

</varlistentry>

368

369

370

<term><option>--version</option></term>

371

372

373

<para>

374

Prints the program version.

375

</para>

376

</listitem>

377

</varlistentry>

378

</variablelist>

379

</refsect1>

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

If the password is a single-line, manually entered passprase,

420

a final trailing newline character should

421

<emphasis>not</emphasis> be printed.

422

</para>

423

<para>

424

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

425

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

426

services not available there.

427

</para>

428

<para>

429

The plugin must exit cleanly and free all allocated resources

430

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

431

runner uses to stop all other plugins when one plugin has

432

output a password and exited cleanly.

433

</para>

434

<para>

435

The plugin must not use resources, like for instance reading

436

from the standard input, without knowing that no other plugin

437

is also using it.

438

</para>

439

<para>

440

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

441

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

442

</para>

443

</refsect2>

444

</refsect1>

445

446

447

<title>FALLBACK</title>

448

<para>

449

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

450

a password on the console using <citerefentry><refentrytitle

451

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

452

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

453

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

454

from the console.

455

</para>

456

</refsect1>

457

458

459

<title>EXIT STATUS</title>

460

<para>

461

Exit status of this program is zero if no errors were

462

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

463

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

464

case.

465

</para>

466

</refsect1>

467

468

469

<title>ENVIRONMENT</title>

470

<para>

471

This program does not use any environment variables itself, it

472

only passes on its environment to all the plugins. The

473

environment passed to plugins can be modified using the

474

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

475

options.

476

</para>

477

</refsect1>

478

479

480

<title>FILES</title>

481

<para>

482

483

484

<term><filename

485

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

486

487

<para>

488

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

489

little to no opportunity to pass command line arguments

490

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

491

read this file and use its contents as

492

whitespace-separated command line options. Also,

493

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

494

of a line is ignored.

495

</para>

496

<para>

497

This program is meant to run in the initial RAM disk

498

environment, so that is where this file is assumed to

499

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

500

file system.

501

</para>

502

<para>

503

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

504

the normal command line options, so the latter can

505

override the former, if need be.

506

</para>

507

<para>

508

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

509

arguments can be changed using the

510

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

511

</para>

512

</listitem>

513

</varlistentry>

514

</variablelist>

515

</para>

516

</refsect1>

517

518

519

520

<para>

521

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

522

specified from within a configuration file.

523

</para>

524

</refsect1>

525

526

527

<title>EXAMPLE</title>

528

529

<para>

530

Normal invocation needs no options:

531

</para>

532

<para>

533

<userinput>&COMMANDNAME;</userinput>

534

</para>

535

</informalexample>

536

537

<para>

538

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

539

</para>

540

<para>

541

542

543

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

544

545

</para>

546

</informalexample>

547

548

<para>

549

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

550

debug mode:

551

</para>

552

<para>

553

554

555

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

556

557

</para>

558

</informalexample>

559

560

<para>

561

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

562

</para>

563

<para>

564

565

566

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

567

568

</para>

569

</informalexample>

570

571

<para>

572

Run plugins from a different directory, read a different

573

configuration file, and add two options to the

574

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

575

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

576

</para>

577

<para>

578

579

580

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

581

582

</para>

583

</informalexample>

584

</refsect1>

585

586

<title>SECURITY</title>

587

<para>

588

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

589

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

590

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

591

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

592

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

593

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

594

set on the plugin executable file (see <citerefentry>

595

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

596

</citerefentry>).

597

</para>

598

<para>

599

If this program is used as a keyscript in <citerefentry

600

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

601

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

602

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

603

for booting from another media and editing the initial RAM disk

604

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

605

since the <citerefentry><refentrytitle

606

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

607

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

608

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

609

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

610

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

611

linkend="fallback"/>).

612

</para>

613

</refsect1>

614

615

616

617

<para>

618

<citerefentry><refentrytitle>cryptsetup</refentrytitle>

619

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

620

<citerefentry><refentrytitle>crypttab</refentrytitle>

621

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

622

<citerefentry><refentrytitle>execve</refentrytitle>

623

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

624

<citerefentry><refentrytitle>mandos</refentrytitle>

625

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

626

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

627

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

628

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

629

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

630

</para>

631

</refsect1>

632

633

</refentry>

634

635

636

637

638