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"/>
76
54
<command>&COMMANDNAME;</command>
77
55
<group rep="repeat">
78
<arg choice="plain"><option>--global-envs=<replaceable
56
<arg choice="plain"><option>--global-env=<replaceable
79
57
>VAR</replaceable><literal>=</literal><replaceable
80
58
>value</replaceable></option></arg>
81
<arg choice="plain"><option>-e
59
<arg choice="plain"><option>-G
82
60
<replaceable>VAR</replaceable><literal>=</literal><replaceable
83
61
>value</replaceable> </option></arg>
86
64
<group rep="repeat">
87
<arg choice="plain"><option>--envs-for=<replaceable
65
<arg choice="plain"><option>--env-for=<replaceable
88
66
>PLUGIN</replaceable><literal>:</literal><replaceable
89
67
>ENV</replaceable><literal>=</literal><replaceable
90
68
>value</replaceable></option></arg>
91
<arg choice="plain"><option>-f<replaceable>
69
<arg choice="plain"><option>-E<replaceable>
92
70
PLUGIN</replaceable><literal>:</literal><replaceable
93
71
>ENV</replaceable><literal>=</literal><replaceable
94
72
>value</replaceable> </option></arg>
149
137
</refsynopsisdiv>
151
139
<refsect1 id="description">
152
140
<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.
142
<command>&COMMANDNAME;</command> is a program which is meant to
143
be specified as <quote>keyscript</quote> in <citerefentry>
144
<refentrytitle>crypttab</refentrytitle>
145
<manvolnum>5</manvolnum></citerefentry> for the root disk. The
146
aim of this program is therefore to output a password, which
147
then <citerefentry><refentrytitle>cryptsetup</refentrytitle>
148
<manvolnum>8</manvolnum></citerefentry> will use to try and
149
unlock the root disk.
152
This program is not meant to be invoked directly, but can be in
153
order to test it. Note that any password obtained will simply
154
be output on standard output.
158
<refsect1 id="purpose">
159
<title>PURPOSE</title>
161
The purpose of this is to enable <emphasis>remote and unattended
162
rebooting</emphasis> of client host computer with an
163
<emphasis>encrypted root file system</emphasis>. See <xref
164
linkend="overview"/> for details.
171
169
<title>OPTIONS</title>
172
<term><option>--global-env
173
<replaceable>VAR</replaceable><literal>=</literal><replaceable
174
>value</replaceable></option></term>
176
<replaceable>VAR</replaceable><literal>=</literal><replaceable
177
>value</replaceable></option></term>
180
This option will add an environment variable setting to
181
all plugins. This will override any inherited environment
188
<term><option>--env-for
189
<replaceable>PLUGIN</replaceable><literal>:</literal
190
><replaceable>ENV</replaceable><literal>=</literal
191
><replaceable>value</replaceable></option></term>
193
<replaceable>PLUGIN</replaceable><literal>:</literal
194
><replaceable>ENV</replaceable><literal>=</literal
195
><replaceable>value</replaceable></option></term>
198
This option will add an environment variable setting to
199
the <replaceable>PLUGIN</replaceable> plugin. This will
200
override any inherited environment variables or
201
environment variables specified using
202
<option>--global-env</option>.
174
208
<term><option>--global-options
175
209
<replaceable>OPTIONS</replaceable></option></term>
177
211
<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.
214
Pass some options to <emphasis>all</emphasis> plugins.
215
<replaceable>OPTIONS</replaceable> is a comma separated
216
list of options. This is not a very useful option, except
217
for specifying the <quote><option>--debug</option></quote>
188
224
<term><option>--options-for
189
225
<replaceable>PLUGIN</replaceable><literal>:</literal
193
229
><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.
232
Pass some options to a specific plugin. <replaceable
233
>PLUGIN</replaceable> is the name (file basename) of a
234
plugin, and <replaceable>OPTIONS</replaceable> is a comma
235
separated list of options.
238
Note that since options are not split on whitespace, the
239
way to pass, to the plugin
240
<quote><filename>foo</filename></quote>, the option
241
<option>--bar</option> with the option argument
242
<quote>baz</quote> is either
243
<userinput>--options-for=foo:--bar=baz</userinput> or
244
<userinput>--options-for=foo:--bar,baz</userinput>, but
245
<emphasis>not</emphasis>
246
<userinput>--options-for="foo:--bar baz"</userinput>.
204
<term><option> --disable
252
<term><option>--disable
205
253
<replaceable>PLUGIN</replaceable></option></term>
207
255
<replaceable>PLUGIN</replaceable></option></term>
210
Disable a specific plugin
258
Disable the plugin named
259
<replaceable>PLUGIN</replaceable>. The plugin will not be
266
<term><option>--enable
267
<replaceable>PLUGIN</replaceable></option></term>
269
<replaceable>PLUGIN</replaceable></option></term>
272
Re-enable the plugin named
273
<replaceable>PLUGIN</replaceable>. This is only useful to
274
undo a previous <option>--disable</option> option, maybe
275
from the config file.
216
281
<term><option>--groupid
217
282
<replaceable>ID</replaceable></option></term>
220
Group ID the plugins will run as
285
Change to group ID <replaceable>ID</replaceable> on
286
startup. The default is 65534. All plugins will be
287
started using this group ID. <emphasis>Note:</emphasis>
288
This must be a number, not a name.
237
308
<replaceable>DIRECTORY</replaceable></option></term>
240
Specify a different plugin directory
311
Specify a different plugin directory. The default is
312
<filename>/lib/mandos/plugins.d</filename>, which will
313
exist in the initial <acronym>RAM</acronym> disk
320
<term><option>--config-file
321
<replaceable>FILE</replaceable></option></term>
324
Specify a different file to read additional options from.
325
See <xref linkend="files"/>. Other command line options
326
will override options specified in the file.
275
371
<term><option>-V</option></term>
278
Prints the program version
374
Prints the program version.
381
<refsect1 id="overview">
382
<title>OVERVIEW</title>
383
<xi:include href="overview.xml"/>
385
This program will run on the client side in the initial
386
<acronym>RAM</acronym> disk environment, and is responsible for
387
getting a password. It does this by running plugins, one of
388
which will normally be the actual client program communicating
392
<refsect1 id="plugins">
393
<title>PLUGINS</title>
395
This program will get a password by running a number of
396
<firstterm>plugins</firstterm>, which are simply executable
397
programs in a directory in the initial <acronym>RAM</acronym>
398
disk environment. The default directory is
399
<filename>/lib/mandos/plugins.d</filename>, but this can be
400
changed with the <option>--plugin-dir</option> option. The
401
plugins are started in parallel, and the first plugin to output
402
a password <emphasis>and</emphasis> exit with a successful exit
403
code will make this plugin-runner output the password from that
404
plugin, stop any other plugins, and exit.
408
<refsect1 id="fallback">
409
<title>FALLBACK</title>
411
If no plugins succeed, this program will, as a fallback, ask for
412
a password on the console using <citerefentry><refentrytitle
413
>getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
414
and output it. This is not meant to be the normal mode of
415
operation, as there is a separate plugin for getting a password
285
420
<refsect1 id="exit_status">
286
421
<title>EXIT STATUS</title>
423
Exit status of this program is zero if no errors were
424
encountered, and otherwise not. The fallback (see <xref
425
linkend="fallback"/>) may or may not have succeeded in either
430
<refsect1 id="environment">
431
<title>ENVIRONMENT</title>
433
This program does not use any environment variables itself, it
434
only passes on its environment to all the plugins. The
435
environment passed to plugins can be modified using the
436
<option>--global-env</option> and <option>--env-for</option>
441
<refsect1 id="files">
292
442
<title>FILES</title>
297
<refsect1 id="notes">
447
>/conf/conf.d/mandos/plugin-runner.conf</filename></term>
450
Since this program will be run as a keyscript, there is
451
little to no opportunity to pass command line arguments
452
to it. Therefore, it will <emphasis>also</emphasis>
453
read this file and use its contents as
454
whitespace-separated command line options. Also,
455
everything from a <quote>#</quote> character to the end
456
of a line is ignored.
459
This program is meant to run in the initial RAM disk
460
environment, so that is where this file is assumed to
461
exist. The file does not need to exist in the normal
465
This file will be processed <emphasis>before</emphasis>
466
the normal command line options, so the latter can
467
override the former, if need be.
470
This file name is the default; the file to read for
471
arguments can be changed using the
472
<option>--config-file</option> option.