/mandos/trunk : revision 133

To get this branch, use:

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

« back to all changes in this revision

Viewing changes to plugin-runner.xml

Committer: Teddy Hogeborn
Date: 2008-08-31 20:01:03 UTC
Revision ID: teddy@fukt.bsnet.se-20080831200103-wvjp5oagtxj7s25g

* plugin-runner.c: Break a couple of long lines.

files modified:
mandos.xml

overview.xml

plugin-runner.xml

plugins.d/password-prompt.xml

Show diffs side-by-side

added added

removed removed

plugin-runner.xml

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

<!ENTITY VERSION "1.0">

<!ENTITY COMMANDNAME "plugin-runner">

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

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

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

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>

158

148

159

149

<title>OPTIONS</title>

160

150

165

155

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

166

156

167

157

<para>

168

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

169

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

170

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

171

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

172

for all plugins.

173

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

174

162

</listitem>

175

163

</varlistentry>

176

164

177

165

178

166

<term><option>--options-for

179

167

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

183

171

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

184

172

185

173

<para>

186

Pass some options to a specific plugin. <replaceable

187

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

188

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

189

separated list of options.

190

</para>

191

<para>

192

Note that since options are not split on whitespace, the

193

way to pass, to the plugin

194

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

195

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

196

<quote>baz</quote> is either

197

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

198

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

199

200

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

201

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

202

178

</listitem>

203

179

</varlistentry>

204

180

209

185

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

210

186

211

187

<para>

212

Disable the plugin named

213

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

214

started.

188

Disable a specific plugin

215

189

</para>

216

190

</listitem>

217

191

</varlistentry>

221

195

222

196

223

197

<para>

224

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

225

startup. The default is 65534. All plugins will be

226

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

227

This must be a number, not a name.

198

Group ID the plugins will run as

228

199

</para>

229

200

</listitem>

230

201

</varlistentry>

234

205

235

206

236

207

<para>

237

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

238

startup. The default is 65534. All plugins will be

239

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

240

This must be a number, not a name.

208

User ID the plugins will run as

241

209

</para>

242

210

</listitem>

243

211

</varlistentry>

247

215

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

248

216

249

217

<para>

250

Specify a different plugin directory. The default is

251

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

252

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

253

environment.

218

Specify a different plugin directory

254

219

</para>

255

220

</listitem>

256

221

</varlistentry>

259

224

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

260

225

261

226

<para>

262

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

263

standard error about what the program is doing. The

264

program will still perform all other functions normally.

265

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

266

mode.

267

</para>

268

<para>

269

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

270

this option. Use

271

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

272

if complete debugging eruption is desired.

227

Debug mode

273

228

</para>

274

229

</listitem>

275

230

</varlistentry>

279

234

280

235

281

236

<para>

282

Gives a help message about options and their meanings.

237

Gives a help message

283

238

</para>

284

239

</listitem>

285

240

</varlistentry>

288

243

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

289

244

290

245

<para>

291

Gives a short usage message.

246

Gives a short usage message

292

247

</para>

293

248

</listitem>

294

249

</varlistentry>

298

253

299

254

300

255

<para>

301

Prints the program version.

256

Prints the program version

302

257

</para>

303

258

</listitem>

304

259

</varlistentry>

305

260

</variablelist>

306

261

</refsect1>

307

262

308

309

<title>OVERVIEW</title>

310

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

311

<para>

312

This program will run on the client side in the initial

313

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

314

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

315

which will normally be the actual client program communicating

316

with the server.

317

</para>

318

</refsect1>

319

320

<title>PLUGINS</title>

321

<para>

322

This program will get a password by running a number of

323

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

324

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

325

disk environment. The default directory is

326

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

327

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

328

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

329

a password and exit with a successful exit code will make this

330

plugin-runner output that password, stop any other plugins, and

331

exit.

332

</para>

333

</refsect1>

334

335

336

<title>FALLBACK</title>

337

<para>

338

</para>

339

</refsect1>

340

263

341

264

<title>EXIT STATUS</title>

342

265

<para>

Older »