/mandos/release : revision 138

To get this branch, use:

bzr branch
http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to plugin-runner.xml

Committer: Teddy Hogeborn
Date: 2008-09-02 06:13:47 UTC
Revision ID: teddy@fukt.bsnet.se-20080902061347-psw61eqt17j425sq

* plugin-runner.c: Changed short option for "--global-env" to "-G",
changed short option for "--env-for" to "-E",
added new option "--enable" ("-e").

files added:
.bzrignore

COPYING

initramfs-tools-hook

initramfs-tools-hook-conf

initramfs-tools-script

legalnotice.xml

mandos-clients.conf.xml

mandos-keygen

mandos-keygen.xml

mandos-options.xml

mandos.conf

mandos.conf.xml

mandos.xml

overview.xml

plugin-runner.xml

plugins.d/password-prompt.xml

plugins.d/password-request.xml

plugins.d/usplash

files removed:
ca.pem

cert.pem

client-cert.pem

client-key.pem

crl.pem

key.pem

files renamed:
mandos-clients.conf => clients.conf

server.py => mandos

plugbasedclient.c => plugin-runner.c

plugins.d/passprompt.c => plugins.d/password-prompt.c

plugins.d/mandosclient.c => plugins.d/password-request.c

files modified:
Makefile

TODO

Show diffs side-by-side

added added

removed removed

plugin-runner.xml

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

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

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

<!ENTITY VERSION "1.0">

<!ENTITY COMMANDNAME "plugin-runner">

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

<title>Mandos Manual</title>

<productname>Mandos</productname>

<productnumber>&VERSION;</productnumber>

<date>&TIMESTAMP;</date>

<firstname>Björn</firstname>

<surname>Påhlsson</surname>

<email>belorn@fukt.bsnet.se</email>

</address>

</author>

<firstname>Teddy</firstname>

<surname>Hogeborn</surname>

<email>teddy@fukt.bsnet.se</email>

</address>

</author>

</authorgroup>

<holder>Teddy Hogeborn</holder>

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

</copyright>

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

</refentryinfo>

<refentrytitle>&COMMANDNAME;</refentrytitle>

<manvolnum>8mandos</manvolnum>

</refmeta>

<refname><command>&COMMANDNAME;</command></refname>

Run Mandos plugins. Pass data from first succesful one.

</refpurpose>

</refnamediv>

<command>&COMMANDNAME;</command>

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

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

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

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

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

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

</group>

<sbr/>

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

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

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

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

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

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

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

</group>

<sbr/>

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

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

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

</group>

<sbr/>

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

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

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

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

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

</group>

<sbr/>

<arg choice="plain"><option>--disable=<replaceable

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

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

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

</group>

<sbr/>

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

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

100

<sbr/>

101

<arg><option>--userid=<replaceable

102

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

103

<sbr/>

104

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

105

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

106

<sbr/>

107

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

108

</cmdsynopsis>

109

110

<command>&COMMANDNAME;</command>

111

112

113

114

</group>

115

</cmdsynopsis>

116

117

<command>&COMMANDNAME;</command>

118

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

119

</cmdsynopsis>

120

121

<command>&COMMANDNAME;</command>

122

123

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

124

125

</group>

126

</cmdsynopsis>

127

</refsynopsisdiv>

128

129

130

<title>DESCRIPTION</title>

131

<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

158

159

<title>OPTIONS</title>

160

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

198

<term><option>--global-options

199

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

200

<term><option>-g

201

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

202

203

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

210

</listitem>

211

</varlistentry>

212

213

214

<term><option>--options-for

215

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

216

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

217

<term><option>-o

218

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

219

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

220

221

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

238

</listitem>

239

</varlistentry>

240

241

242

<term><option> --disable

243

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

244

<term><option>-d

245

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

246

247

<para>

248

Disable the plugin named

249

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

250

started.

251

</para>

252

</listitem>

253

</varlistentry>

254

255

256

<term><option>--groupid

257

258

259

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

264

</para>

265

</listitem>

266

</varlistentry>

267

268

269

<term><option>--userid

270

271

272

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

277

</para>

278

</listitem>

279

</varlistentry>

280

281

282

<term><option>--plugin-dir

283

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

284

285

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

290

</para>

291

</listitem>

292

</varlistentry>

293

294

295

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

296

297

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

309

</para>

310

</listitem>

311

</varlistentry>

312

313

314

315

316

317

<para>

318

Gives a help message about options and their meanings.

319

</para>

320

</listitem>

321

</varlistentry>

322

323

324

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

325

326

<para>

327

Gives a short usage message.

328

</para>

329

</listitem>

330

</varlistentry>

331

332

333

<term><option>--version</option></term>

334

335

336

<para>

337

Prints the program version.

338

</para>

339

</listitem>

340

</varlistentry>

341

</variablelist>

342

</refsect1>

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

383

384

<title>EXIT STATUS</title>

385

<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

400

401

<title>FILES</title>

402

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

425

</para>

426

</refsect1>

427

428

429

430

<para>

431

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

432

plugins.

433

</para>

434

</refsect1>

435

436

437

<title>EXAMPLE</title>

438

<para>

439

</para>

440

</refsect1>

441

442

443

<title>SECURITY</title>

444

<para>

445

</para>

446

</refsect1>

447

448

449

450

<para>

451

<citerefentry><refentrytitle>cryptsetup</refentrytitle>

452

<manvolnum>8</manvolnum></citerefentry>,

453

<citerefentry><refentrytitle>mandos</refentrytitle>

454

<manvolnum>8</manvolnum></citerefentry>,

455

<citerefentry><refentrytitle>password-prompt</refentrytitle>

456

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

457

<citerefentry><refentrytitle>password-request</refentrytitle>

458

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

459

</para>

460

</refsect1>

461

462

</refentry>

463

464

465

466

467

Older »