3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY VERSION "1.0">
5
5
<!ENTITY COMMANDNAME "plugin-runner">
6
<!ENTITY TIMESTAMP "2008-08-31">
6
<!ENTITY TIMESTAMP "2008-09-01">
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
11
<title>Mandos Manual</title>
12
12
<!-- Nwalsh’s docbook scripts use this to generate the footer: -->
34
34
<holder>Teddy Hogeborn</holder>
35
35
<holder>Björn Påhlsson</holder>
39
This manual page is free software: you can redistribute it
40
and/or modify it under the terms of the GNU General Public
41
License as published by the Free Software Foundation,
42
either version 3 of the License, or (at your option) any
47
This manual page is distributed in the hope that it will
48
be useful, but WITHOUT ANY WARRANTY; without even the
49
implied warranty of MERCHANTABILITY or FITNESS FOR A
50
PARTICULAR PURPOSE. See the GNU General Public License
55
You should have received a copy of the GNU General Public
56
License along with this program; If not, see
57
<ulink url="http://www.gnu.org/licenses/"/>.
37
<xi:include href="legalnotice.xml"/>
149
127
</refsynopsisdiv>
151
129
<refsect1 id="description">
152
130
<title>DESCRIPTION</title>
154
<command>&COMMANDNAME;</command> is a plugin runner that waits
155
for any of its plugins to return sucessfull with a password, and
156
passes it to cryptsetup as stdout message. This command is not
157
meant to be invoked directly, but is instead meant to be run by
158
cryptsetup by being specified in /etc/crypttab as a keyscript
159
and subsequlently started in the initrd environment. See
160
<citerefentry><refentrytitle>crypttab</refentrytitle>
161
<manvolnum>5</manvolnum></citerefentry> for more information on
166
plugins is looked for in the plugins directory which by default will be
167
/conf/conf.d/mandos/plugins.d if not changed by option --plugin-dir.
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.
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.
148
<refsect1 id="purpose">
149
<title>PURPOSE</title>
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.
171
159
<title>OPTIONS</title>
177
165
<replaceable>OPTIONS</replaceable></option></term>
180
Global options given to all plugins as additional start
181
arguments. Options are specified with a -o flag followed
182
by a comma separated string of options.
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>
188
178
<term><option>--options-for
189
179
<replaceable>PLUGIN</replaceable><literal>:</literal
193
183
><replaceable>OPTION</replaceable></option></term>
196
Plugin specific options given to the plugin as additional
197
start arguments. Options are specified with a -o flag
198
followed by a comma separated string of options.
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.
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
<emphasis>not</emphasis>
200
<userinput>--options-for="foo:--bar baz"</userinput>.
217
221
<replaceable>ID</replaceable></option></term>
220
Group ID the plugins will run as
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.
227
234
<replaceable>ID</replaceable></option></term>
230
User ID the plugins will run as
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.
237
247
<replaceable>DIRECTORY</replaceable></option></term>
240
Specify a different plugin directory
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
246
259
<term><option>--debug</option></term>
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
269
The plugins will <emphasis>not</emphasis> be affected by
271
<userinput><option>--global-options=--debug</option></userinput>
272
if complete debugging eruption is desired.
275
298
<term><option>-V</option></term>
278
Prints the program version
301
Prints the program version.
308
<refsect1 id="overview">
309
<title>OVERVIEW</title>
310
<xi:include href="overview.xml"/>
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
319
<refsect1 id="plugins">
320
<title>PLUGINS</title>
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
336
<title>FALLBACK</title>
285
340
<refsect1 id="exit_status">
286
341
<title>EXIT STATUS</title>