/mandos/trunk : revision 24.1.78

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

171

</para>

172

</listitem>

173

</varlistentry>

174

175

176

<term><option>--env-for

177

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

178

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

179

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

180

<term><option>-f

181

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

182

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

183

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

184

185

<para>

186

</para>

187

</listitem>

188

</varlistentry>

189

190

152

191

<term><option>--global-options

153

192

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

154

193

<term><option>-g

155

194

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

156

195

157

196

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

197

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

198

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

199

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

200

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

201

for all plugins.

202

</para>

162

203

</listitem>

163

204

</varlistentry>

164

205

165

206

166

207

<term><option>--options-for

167

208

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

171

212

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

172

213

173

214

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

215

Pass some options to a specific plugin. <replaceable

216

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

217

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

218

separated list of options.

219

</para>

220

<para>

221

Note that since options are not split on whitespace, the

222

way to pass, to the plugin

223

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

224

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

225

<quote>baz</quote> is either

226

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

227

<userinput>--options-for=foo:--bar,baz</userinput>, but

228

229

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

230

</para>

178

231

</listitem>

179

232

</varlistentry>

180

233

185

238

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

186

239

187

240

<para>

188

Disable a specific plugin

241

Disable the plugin named

242

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

243

started.

189

244

</para>

190

245

</listitem>

191

246

</varlistentry>

195

250

196

251

197

252

<para>

198

Group ID the plugins will run as

253

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

254

startup. The default is 65534. All plugins will be

255

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

256

This must be a number, not a name.

199

257

</para>

200

258

</listitem>

201

259

</varlistentry>

205

263

206

264

207

265

<para>

208

User ID the plugins will run as

266

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

267

startup. The default is 65534. All plugins will be

268

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

269

This must be a number, not a name.

209

270

</para>

210

271

</listitem>

211

272

</varlistentry>

215

276

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

216

277

217

278

<para>

218

Specify a different plugin directory

279

Specify a different plugin directory. The default is

280

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

281

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

282

environment.

219

283

</para>

220

284

</listitem>

221

285

</varlistentry>

224

288

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

225

289

226

290

<para>

227

Debug mode

291

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

292

standard error about what the program is doing. The

293

program will still perform all other functions normally.

294

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

295

mode.

296

</para>

297

<para>

298

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

299

this option. Use

300

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

301

if complete debugging eruption is desired.

228

302

</para>

229

303

</listitem>

230

304

</varlistentry>

234

308

235

309

236

310

<para>

237

Gives a help message

311

Gives a help message about options and their meanings.

238

312

</para>

239

313

</listitem>

240

314

</varlistentry>

243

317

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

244

318

245

319

<para>

246

Gives a short usage message

320

Gives a short usage message.

247

321

</para>

248

322

</listitem>

249

323

</varlistentry>

253

327

254

328

255

329

<para>

256

Prints the program version

330

Prints the program version.

257

331

</para>

258

332

</listitem>

259

333

</varlistentry>

260

334

</variablelist>

261

335

</refsect1>

262

336

337

338

<title>OVERVIEW</title>

339

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

340

<para>

341

This program will run on the client side in the initial

342

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

343

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

344

which will normally be the actual client program communicating

345

with the server.

346

</para>

347

</refsect1>

348

349

<title>PLUGINS</title>

350

<para>

351

This program will get a password by running a number of

352

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

353

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

354

disk environment. The default directory is

355

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

356

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

357

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

358

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

359

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

360

plugin, stop any other plugins, and exit.

361

</para>

362

</refsect1>

363

364

365

<title>FALLBACK</title>

366

<para>

367

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

368

a password on the console using <citerefentry><refentrytitle

369

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

370

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

371

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

372

from the console.

373

</para>

374

</refsect1>

375

263

376

264

377

<title>EXIT STATUS</title>

265

378

<para>

266

</para>

267

</refsect1>

268

379

Exit status of this program is zero if no errors were

380

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

381

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

382

case.

383

</para>

384

</refsect1>

385

386

387

<title>ENVIRONMENT</title>

388

<para>

389

390

</para>

391

</refsect1>

392

269

393

270

394

<title>FILES</title>

271

395

<para>

272

</para>

273

</refsect1>

274

275

276

<title>NOTES</title>

277

<para>

396

397

398

<term><filename

399

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

400

401

<para>

402

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

403

little to no opportunity to pass command line arguments

404

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

405

read this file and use its contents as

406

whitespace-separated command line options. Also,

407

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

408

of a line is ignored.

409

</para>

410

</listitem>

411

</varlistentry>

412

</variablelist>

278

413

</para>

279

414

</refsect1>

280

415

283

418

<para>

284

419

</para>

285

420

</refsect1>

286

421

287

422

288

423

<title>EXAMPLE</title>

289

424

<para>

290

425

</para>

291

426

</refsect1>

292

427

293

428

294

429

<title>SECURITY</title>

295

430

<para>

296

431

</para>

297

432

</refsect1>

298

433

299

434

300

435

301

436

<para>

309

444

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

310

445

</para>

311

446

</refsect1>

312

447

313

448

</refentry>

314

449

315

450