/mandos/trunk : revision 138

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

6

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

7

]>

8

9

53

54

<command>&COMMANDNAME;</command>

55

56

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

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

62

</group>

63

<sbr/>

64

65

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

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>

125

</group>

126

</cmdsynopsis>

127

</refsynopsisdiv>

128

129

130

<title>DESCRIPTION</title>

131

<para>

132

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

133

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

134

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

135

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

136

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

137

and subsequlently started in the initrd environment. See

138

<citerefentry><refentrytitle>crypttab</refentrytitle>

139

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

140

keyscripts.

141

</para>

142

143

<para>

144

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

145

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

146

</para>

147

</refsect1>

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

148

158

149

159

<title>OPTIONS</title>

150

160

151

161

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

152

198

<term><option>--global-options

153

199

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

154

200

<term><option>-g

155

201

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

156

202

157

203

<para>

158

Global options given to all plugins as additional start

159

arguments. Options are specified with a -o flag followed

160

by a comma separated string of options.

161

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

162

210

</listitem>

163

211

</varlistentry>

164

212

165

213

166

214

<term><option>--options-for

167

215

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

171

219

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

172

220

173

221

<para>

174

Plugin specific options given to the plugin as additional

175

start arguments. Options are specified with a -o flag

176

followed by a comma separated string of options.

177

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

178

238

</listitem>

179

239

</varlistentry>

180

240

185

245

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

186

246

187

247

<para>

188

Disable a specific plugin

248

Disable the plugin named

249

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

250

started.

189

251

</para>

190

252

</listitem>

191

253

</varlistentry>

195

257

196

258

197

259

<para>

198

Group ID the plugins will run as

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.

199

264

</para>

200

265

</listitem>

201

266

</varlistentry>

205

270

206

271

207

272

<para>

208

User ID the plugins will run as

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.

209

277

</para>

210

278

</listitem>

211

279

</varlistentry>

215

283

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

216

284

217

285

<para>

218

Specify a different plugin directory

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.

219

290

</para>

220

291

</listitem>

221

292

</varlistentry>

224

295

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

225

296

226

297

<para>

227

Debug mode

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.

228

309

</para>

229

310

</listitem>

230

311

</varlistentry>

234

315

235

316

236

317

<para>

237

Gives a help message

318

Gives a help message about options and their meanings.

238

319

</para>

239

320

</listitem>

240

321

</varlistentry>

243

324

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

244

325

245

326

<para>

246

Gives a short usage message

327

Gives a short usage message.

247

328

</para>

248

329

</listitem>

249

330

</varlistentry>

253

334

254

335

255

336

<para>

256

Prints the program version

337

Prints the program version.

257

338

</para>

258

339

</listitem>

259

340

</varlistentry>

260

341

</variablelist>

261

342

</refsect1>

262

343

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

263

383

264

384

<title>EXIT STATUS</title>

265

385

<para>

266

</para>

267

</refsect1>

268

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

269

400

270

401

<title>FILES</title>

271

402

<para>

272

</para>

273

</refsect1>

274

275

276

<title>NOTES</title>

277

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

278

425

</para>

279

426

</refsect1>

280

427

281

428

282

429

283

430

<para>

431

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

432

plugins.

284

433

</para>

285

434

</refsect1>

286

435

287

436

288

437

<title>EXAMPLE</title>

289

438

<para>

290

439

</para>

291

440

</refsect1>

292

441

293

442

294

443

<title>SECURITY</title>

295

444

<para>

296

445

</para>

297

446

</refsect1>

298

447

299

448

300

449

301

450

<para>

309

458

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

310

459

</para>

311

460

</refsect1>

312

461

313

462

</refentry>

314

463

315

464