/mandos/release : revision 125

1

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

1

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

2

<?xml-stylesheet type="text/xsl"

3

href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>

2

4

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

3

5

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

4

6

<!ENTITY VERSION "1.0">

5

7

<!ENTITY COMMANDNAME "plugin-runner">

6

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

8

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

7

9

]>

8

10

9

11

10

12

11

13

<title>Mandos Manual</title>

12

14

13

15

<productname>Mandos</productname>

14

16

<productnumber>&VERSION;</productnumber>

15

17

<date>&TIMESTAMP;</date>

31

33

</authorgroup>

32

34

33

35

34

<holder>Teddy Hogeborn</holder>

35

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

36

<holder>Teddy Hogeborn & Björn Påhlsson</holder>

36

37

</copyright>

37

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

38

39

<para>

40

This manual page is free software: you can redistribute it

41

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

42

License as published by the Free Software Foundation,

43

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

44

later version.

45

</para>

46

47

<para>

48

This manual page is distributed in the hope that it will

49

be useful, but WITHOUT ANY WARRANTY; without even the

50

implied warranty of MERCHANTABILITY or FITNESS FOR A

51

PARTICULAR PURPOSE. See the GNU General Public License

52

for more details.

53

</para>

54

55

<para>

56

You should have received a copy of the GNU General Public

57

License along with this program; If not, see

58

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

59

</para>

60

</legalnotice>

38

61

</refentryinfo>

39

62

40

63

53

76

54

77

<command>&COMMANDNAME;</command>

55

78

56

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

79

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

57

80

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

58

81

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

59

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

82

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

60

83

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

61

84

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

62

85

</group>

63

86

<sbr/>

64

87

65

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

88

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

66

89

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

67

90

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

68

91

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

69

92

70

93

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

71

94

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

72

95

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

83

106

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

84

107

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

85

108

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

86

109

87

110

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

88

111

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

89

112

</group>

95

118

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

96

119

</group>

97

120

<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

121

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

106

122

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

107

123

<sbr/>

111

127

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

112

128

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

113

129

<sbr/>

114

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

115

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

116

<sbr/>

117

130

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

118

131

</cmdsynopsis>

119

132

120

133

<command>&COMMANDNAME;</command>

121

134

122

123

135

136

124

137

</group>

125

138

</cmdsynopsis>

126

139

127

140

<command>&COMMANDNAME;</command>

128

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

141

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

129

142

</cmdsynopsis>

130

143

131

144

<command>&COMMANDNAME;</command>

132

145

133

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

134

146

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

147

135

148

</group>

136

149

</cmdsynopsis>

137

150

</refsynopsisdiv>

138

151

139

152

140

153

<title>DESCRIPTION</title>

141

154

<para>

142

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

143

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

144

<refentrytitle>crypttab</refentrytitle>

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.

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

155

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

156

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

157

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

158

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

159

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

160

and subsequlently started in the initrd environment. See

161

<citerefentry><refentrytitle>crypttab</refentrytitle>

162

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

163

keyscripts.

164

</para>

165

166

<para>

167

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

168

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

169

</para>

170

</refsect1>

168

171

169

172

<title>OPTIONS</title>

170

173

171

174

172

<term><option>--global-env

173

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

174

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

175

<term><option>-e

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

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

175

<term><option>--global-options

209

176

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

210

177

<term><option>-g

211

178

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

212

179

213

180

<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

for all plugins.

219

</para>

181

Global options given to all plugins as additional start

182

arguments. Options are specified with a -o flag followed

183

by a comma separated string of options.

184

</para>

220

185

</listitem>

221

186

</varlistentry>

222

187

223

188

224

189

<term><option>--options-for

225

190

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

229

194

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

230

195

231

196

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

245

246

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

247

</para>

197

Plugin specific options given to the plugin as additional

198

start arguments. Options are specified with a -o flag

199

followed by a comma separated string of options.

200

</para>

248

201

</listitem>

249

202

</varlistentry>

250

203

251

204

252

<term><option>--disable

205

<term><option> --disable

253

206

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

254

207

<term><option>-d

255

208

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

256

209

257

210

<para>

258

Disable the plugin named

259

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

260

started.

211

Disable a specific plugin

261

212

</para>

262

213

</listitem>

263

214

</varlistentry>

264

215

265

216

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

281

217

<term><option>--groupid

282

218

283

219

284

220

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

221

Group ID the plugins will run as

289

222

</para>

290

223

</listitem>

291

224

</varlistentry>

295

228

296

229

297

230

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

231

User ID the plugins will run as

302

232

</para>

303

233

</listitem>

304

234

</varlistentry>

308

238

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

309

239

310

240

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

241

Specify a different plugin directory

327

242

</para>

328

243

</listitem>

329

244

</varlistentry>

332

247

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

333

248

334

249

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

250

Debug mode

346

251

</para>

347

252

</listitem>

348

253

</varlistentry>

352

257

353

258

354

259

<para>

355

Gives a help message about options and their meanings.

260

Gives a help message

356

261

</para>

357

262

</listitem>

358

263

</varlistentry>

361

266

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

362

267

363

268

<para>

364

Gives a short usage message.

269

Gives a short usage message

365

270

</para>

366

271

</listitem>

367

272

</varlistentry>

371

276

372

277

373

278

<para>

374

Prints the program version.

279

Prints the program version

375

280

</para>

376

281

</listitem>

377

282

</varlistentry>

378

283

</variablelist>

379

284

</refsect1>

380

285

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

</refsect1>

407

408

409

<title>FALLBACK</title>

410

<para>

411

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

412

a password on the console using <citerefentry><refentrytitle

413

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

414

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

415

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

416

from the console.

417

</para>

418

</refsect1>

419

420

286

421

287

<title>EXIT STATUS</title>

422

288

<para>

423

Exit status of this program is zero if no errors were

424

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

425

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

426

case.

427

</para>

428

</refsect1>

429

430

431

<title>ENVIRONMENT</title>

432

<para>

433

This program does not use any environment variables itself, it

434

only passes on its environment to all the plugins. The

435

environment passed to plugins can be modified using the

436

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

437

optins.

438

</para>

439

</refsect1>

440

441

289

</para>

290

</refsect1>

291

292

442

293

<title>FILES</title>

443

294

<para>

444

445

446

<term><filename

447

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

448

449

<para>

450

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

451

little to no opportunity to pass command line arguments

452

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

453

read this file and use its contents as

454

whitespace-separated command line options. Also,

455

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

456

of a line is ignored.

457

</para>

458

<para>

459

This program is meant to run in the initial RAM disk

460

environment, so that is where this file is assumed to

461

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

462

file system.

463

</para>

464

<para>

465

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

466

the normal command line options, so the latter can

467

override the former, if need be.

468

</para>

469

<para>

470

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

471

arguments can be changed using the

472

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

473

</para>

474

</listitem>

475

</varlistentry>

476

</variablelist>

295

</para>

296

</refsect1>

297

298

299

<title>NOTES</title>

300

<para>

477

301

</para>

478

302

</refsect1>

479

303

482

306

<para>

483

307

</para>

484

308

</refsect1>

485

309

486

310

487

311

<title>EXAMPLE</title>

488

312

<para>

489

313

</para>

490

314

</refsect1>

491

315

492

316

493

317

<title>SECURITY</title>

494

318

<para>

495

319

</para>

496

320

</refsect1>

497

321

498

322

499

323

500

324

<para>

508

332

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

509

333

</para>

510

334

</refsect1>

511

335

512

336

</refentry>

513

337

514

338