/mandos/release : revision 130

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-08-31">

7

]>

8

9

9

10

11

<title>Mandos Manual</title>

12

34

<holder>Teddy Hogeborn</holder>

35

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

36

</copyright>

37

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

37

38

<para>

39

This manual page is free software: you can redistribute it

40

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

41

License as published by the Free Software Foundation,

42

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

43

later version.

44

</para>

45

46

<para>

47

This manual page is distributed in the hope that it will

48

be useful, but WITHOUT ANY WARRANTY; without even the

49

implied warranty of MERCHANTABILITY or FITNESS FOR A

50

PARTICULAR PURPOSE. See the GNU General Public License

51

for more details.

52

</para>

53

54

<para>

55

You should have received a copy of the GNU General Public

56

License along with this program; If not, see

57

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

58

</para>

59

</legalnotice>

38

60

</refentryinfo>

39

61

40

62

53

75

54

76

<command>&COMMANDNAME;</command>

55

77

56

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

78

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

57

79

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

58

80

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

59

81

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

62

84

</group>

63

85

<sbr/>

64

86

65

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

87

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

66

88

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

67

89

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

68

90

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

125

147

</group>

126

148

</cmdsynopsis>

127

149

</refsynopsisdiv>

128

150

129

151

130

152

<title>DESCRIPTION</title>

131

153

<para>

132

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

133

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

134

<refentrytitle>crypttab</refentrytitle>

135

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

136

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

137

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

138

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

139

unlock the root disk.

140

</para>

141

<para>

142

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

143

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

144

be output on standard output.

145

</para>

146

</refsect1>

147

148

149

<title>PURPOSE</title>

150

<para>

151

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

152

rebooting</emphasis> of client host computer with an

153

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

154

linkend="overview"/> for details.

155

</para>

156

</refsect1>

157

154

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

155

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

156

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

157

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

158

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

159

and subsequlently started in the initrd environment. See

160

<citerefentry><refentrytitle>crypttab</refentrytitle>

161

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

162

keyscripts.

163

</para>

164

165

<para>

166

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

167

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

168

</para>

169

</refsect1>

158

170

159

171

<title>OPTIONS</title>

160

172

161

173

162

<term><option>--global-env

163

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

164

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

165

<term><option>-e

166

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

167

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

168

169

<para>

170

This option will add an environment variable setting to

171

all plugins. This will override any inherited environment

172

variable.

173

</para>

174

</listitem>

175

</varlistentry>

176

177

178

<term><option>--env-for

179

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

180

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

181

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

182

<term><option>-f

183

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

184

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

185

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

186

187

<para>

188

This option will add an environment variable setting to

189

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

190

override any inherited environment variables or

191

environment variables specified using

192

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

193

</para>

194

</listitem>

195

</varlistentry>

196

197

198

174

<term><option>--global-options

199

175

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

200

176

<term><option>-g

201

177

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

202

178

203

179

<para>

204

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

205

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

206

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

207

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

208

for all plugins.

209

</para>

180

Global options given to all plugins as additional start

181

arguments. Options are specified with a -o flag followed

182

by a comma separated string of options.

183

</para>

210

184

</listitem>

211

185

</varlistentry>

212

186

213

187

214

188

<term><option>--options-for

215

189

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

219

193

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

220

194

221

195

<para>

222

Pass some options to a specific plugin. <replaceable

223

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

224

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

225

separated list of options.

226

</para>

227

<para>

228

Note that since options are not split on whitespace, the

229

way to pass, to the plugin

230

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

231

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

232

<quote>baz</quote> is either

233

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

237

</para>

196

Plugin specific options given to the plugin as additional

197

start arguments. Options are specified with a -o flag

198

followed by a comma separated string of options.

199

</para>

238

200

</listitem>

239

201

</varlistentry>

240

202

245

207

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

246

208

247

209

<para>

248

Disable the plugin named

249

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

250

started.

210

Disable a specific plugin

251

211

</para>

252

212

</listitem>

253

213

</varlistentry>

257

217

258

218

259

219

<para>

260

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

261

startup. The default is 65534. All plugins will be

262

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

263

This must be a number, not a name.

220

Group ID the plugins will run as

264

221

</para>

265

222

</listitem>

266

223

</varlistentry>

270

227

271

228

272

229

<para>

273

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

274

startup. The default is 65534. All plugins will be

275

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

276

This must be a number, not a name.

230

User ID the plugins will run as

277

231

</para>

278

232

</listitem>

279

233

</varlistentry>

283

237

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

284

238

285

239

<para>

286

Specify a different plugin directory. The default is

287

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

288

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

289

environment.

240

Specify a different plugin directory

290

241

</para>

291

242

</listitem>

292

243

</varlistentry>

295

246

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

296

247

297

248

<para>

298

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

299

standard error about what the program is doing. The

300

program will still perform all other functions normally.

301

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

302

mode.

303

</para>

304

<para>

305

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

306

this option. Use

307

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

308

if complete debugging eruption is desired.

249

Debug mode

309

250

</para>

310

251

</listitem>

311

252

</varlistentry>

315

256

316

257

317

258

<para>

318

Gives a help message about options and their meanings.

259

Gives a help message

319

260

</para>

320

261

</listitem>

321

262

</varlistentry>

324

265

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

325

266

326

267

<para>

327

Gives a short usage message.

268

Gives a short usage message

328

269

</para>

329

270

</listitem>

330

271

</varlistentry>

334

275

335

276

336

277

<para>

337

Prints the program version.

278

Prints the program version

338

279

</para>

339

280

</listitem>

340

281

</varlistentry>

341

282

</variablelist>

342

283

</refsect1>

343

284

344

345

<title>OVERVIEW</title>

346

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

347

<para>

348

This program will run on the client side in the initial

349

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

350

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

351

which will normally be the actual client program communicating

352

with the server.

353

</para>

354

</refsect1>

355

356

<title>PLUGINS</title>

357

<para>

358

This program will get a password by running a number of

359

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

360

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

361

disk environment. The default directory is

362

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

363

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

364

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

365

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

366

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

367

plugin, stop any other plugins, and exit.

368

</para>

369

</refsect1>

370

371

372

<title>FALLBACK</title>

373

<para>

374

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

375

a password on the console using <citerefentry><refentrytitle

376

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

377

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

378

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

379

from the console.

380

</para>

381

</refsect1>

382

383

285

384

286

<title>EXIT STATUS</title>

385

287

<para>

386

Exit status of this program is zero if no errors were

387

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

388

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

389

case.

390

</para>

391

</refsect1>

392

393

394

<title>ENVIRONMENT</title>

395

<para>

396

397

</para>

398

</refsect1>

399

288

</para>

289

</refsect1>

290

400

291

401

292

<title>FILES</title>

402

293

<para>

403

404

405

<term><filename

406

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

407

408

<para>

409

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

410

little to no opportunity to pass command line arguments

411

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

412

read this file and use its contents as

413

whitespace-separated command line options. Also,

414

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

415

of a line is ignored.

416

</para>

417

<para>

418

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

419

the normal command line options, so the latter can

420

override the former, if need be.

421

</para>

422

</listitem>

423

</varlistentry>

424

</variablelist>

294

</para>

295

</refsect1>

296

297

298

<title>NOTES</title>

299

<para>

425

300

</para>

426

301

</refsect1>

427

302

428

303

429

304

430

305

<para>

431

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

432

plugins.

433

306

</para>

434

307

</refsect1>

435

308

436

309

437

310

<title>EXAMPLE</title>

438

311

<para>

439

312

</para>

440

313

</refsect1>

441

314

442

315

443

316

<title>SECURITY</title>

444

317

<para>

445

318

</para>

446

319

</refsect1>

447

320

448

321

449

322

450

323

<para>

458

331

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

459

332

</para>

460

333

</refsect1>

461

334

462

335

</refentry>

463

336

464

337