/mandos/release : revision 129

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

8

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

7

9

]>

8

10

9

11

10

12

11

13

<title>Mandos Manual</title>

12

14

34

36

<holder>Teddy Hogeborn</holder>

35

37

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

36

38

</copyright>

37

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

39

40

<para>

41

This manual page is free software: you can redistribute it

42

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

43

License as published by the Free Software Foundation,

44

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

45

later version.

46

</para>

47

48

<para>

49

This manual page is distributed in the hope that it will

50

be useful, but WITHOUT ANY WARRANTY; without even the

51

implied warranty of MERCHANTABILITY or FITNESS FOR A

52

PARTICULAR PURPOSE. See the GNU General Public License

53

for more details.

54

</para>

55

56

<para>

57

You should have received a copy of the GNU General Public

58

License along with this program; If not, see

59

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

60

</para>

61

</legalnotice>

38

62

</refentryinfo>

39

63

40

64

53

77

54

78

<command>&COMMANDNAME;</command>

55

79

56

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

80

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

57

81

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

58

82

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

59

83

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

62

86

</group>

63

87

<sbr/>

64

88

65

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

89

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

66

90

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

67

91

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

68

92

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

125

149

</group>

126

150

</cmdsynopsis>

127

151

</refsynopsisdiv>

128

152

129

153

130

154

<title>DESCRIPTION</title>

131

155

<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

156

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

157

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

158

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

159

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

160

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

161

and subsequlently started in the initrd environment. See

162

<citerefentry><refentrytitle>crypttab</refentrytitle>

163

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

164

keyscripts.

165

</para>

166

167

<para>

168

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

169

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

170

</para>

171

</refsect1>

158

172

159

173

<title>OPTIONS</title>

160

174

161

175

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

176

<term><option>--global-options

199

177

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

200

178

<term><option>-g

201

179

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

202

180

203

181

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

182

Global options given to all plugins as additional start

183

arguments. Options are specified with a -o flag followed

184

by a comma separated string of options.

185

</para>

210

186

</listitem>

211

187

</varlistentry>

212

188

213

189

214

190

<term><option>--options-for

215

191

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

219

195

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

220

196

221

197

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

198

Plugin specific options given to the plugin as additional

199

start arguments. Options are specified with a -o flag

200

followed by a comma separated string of options.

201

</para>

238

202

</listitem>

239

203

</varlistentry>

240

204

245

209

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

246

210

247

211

<para>

248

Disable the plugin named

249

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

250

started.

212

Disable a specific plugin

251

213

</para>

252

214

</listitem>

253

215

</varlistentry>

257

219

258

220

259

221

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

222

Group ID the plugins will run as

264

223

</para>

265

224

</listitem>

266

225

</varlistentry>

270

229

271

230

272

231

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

232

User ID the plugins will run as

277

233

</para>

278

234

</listitem>

279

235

</varlistentry>

283

239

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

284

240

285

241

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

242

Specify a different plugin directory

290

243

</para>

291

244

</listitem>

292

245

</varlistentry>

295

248

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

296

249

297

250

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

251

Debug mode

309

252

</para>

310

253

</listitem>

311

254

</varlistentry>

315

258

316

259

317

260

<para>

318

Gives a help message about options and their meanings.

261

Gives a help message

319

262

</para>

320

263

</listitem>

321

264

</varlistentry>

324

267

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

325

268

326

269

<para>

327

Gives a short usage message.

270

Gives a short usage message

328

271

</para>

329

272

</listitem>

330

273

</varlistentry>

334

277

335

278

336

279

<para>

337

Prints the program version.

280

Prints the program version

338

281

</para>

339

282

</listitem>

340

283

</varlistentry>

341

284

</variablelist>

342

285

</refsect1>

343

286

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

287

384

288

<title>EXIT STATUS</title>

385

289

<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

290

</para>

291

</refsect1>

292

400

293

401

294

<title>FILES</title>

402

295

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

296

</para>

297

</refsect1>

298

299

300

<title>NOTES</title>

301

<para>

425

302

</para>

426

303

</refsect1>

427

304

428

305

429

306

430

307

<para>

431

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

432

plugins.

433

308

</para>

434

309

</refsect1>

435

310

436

311

437

312

<title>EXAMPLE</title>

438

313

<para>

439

314

</para>

440

315

</refsect1>

441

316

442

317

443

318

<title>SECURITY</title>

444

319

<para>

445

320

</para>

446

321

</refsect1>

447

322

448

323

449

324

450

325

<para>

458

333

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

459

334

</para>

460

335

</refsect1>

461

336

462

337

</refentry>

463

338

464

339