69
46
<refname><command>&COMMANDNAME;</command></refname>
71
get password for encrypted rootdisk
48
Run Mandos plugins. Pass data from first succesful one.
77
54
<command>&COMMANDNAME;</command>
78
<arg choice='opt'>--global-options<arg choice='plain'>OPTIONS</arg></arg>
79
<arg choice='opt'>--options-for<arg choice='plain'>PLUGIN:OPTIONS</arg></arg>
80
<arg choice='opt'>--disable<arg choice='plain'>PLUGIN</arg></arg>
81
<arg choice='opt'>--groupid<arg choice='plain'>ID</arg></arg>
82
<arg choice='opt'>--userid<arg choice='plain'>ID</arg></arg>
83
<arg choice='opt'>--plugin-dir<arg choice='plain'>DIRECTORY</arg></arg>
84
<arg choice='opt'>--debug</arg>
87
<command>&COMMANDNAME;</command>
88
<arg choice='plain'>--help</arg>
91
<command>&COMMANDNAME;</command>
92
<arg choice='plain'>--usage</arg>
95
<command>&COMMANDNAME;</command>
96
<arg choice='plain'>--version</arg>
56
<arg choice="plain"><option>--global-env=<replaceable
57
>VAR</replaceable><literal>=</literal><replaceable
58
>value</replaceable></option></arg>
59
<arg choice="plain"><option>-G
60
<replaceable>VAR</replaceable><literal>=</literal><replaceable
61
>value</replaceable> </option></arg>
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>
69
<arg choice="plain"><option>-E<replaceable>
70
PLUGIN</replaceable><literal>:</literal><replaceable
71
>ENV</replaceable><literal>=</literal><replaceable
72
>value</replaceable> </option></arg>
76
<arg choice="plain"><option>--global-options=<replaceable
77
>OPTIONS</replaceable></option></arg>
78
<arg choice="plain"><option>-g<replaceable>
79
OPTIONS</replaceable> </option></arg>
83
<arg choice="plain"><option>--options-for=<replaceable
84
>PLUGIN</replaceable><literal>:</literal><replaceable
85
>OPTIONS</replaceable></option></arg>
86
<arg choice="plain"><option>-o<replaceable>
87
PLUGIN</replaceable><literal>:</literal><replaceable
88
>OPTIONS</replaceable> </option></arg>
92
<arg choice="plain"><option>--disable=<replaceable
93
>PLUGIN</replaceable></option></arg>
94
<arg choice="plain"><option>-d
95
<replaceable>PLUGIN</replaceable> </option></arg>
99
<arg choice="plain"><option>--enable=<replaceable
100
>PLUGIN</replaceable></option></arg>
101
<arg choice="plain"><option>-e
102
<replaceable>PLUGIN</replaceable> </option></arg>
105
<arg><option>--groupid=<replaceable
106
>ID</replaceable></option></arg>
108
<arg><option>--userid=<replaceable
109
>ID</replaceable></option></arg>
111
<arg><option>--plugin-dir=<replaceable
112
>DIRECTORY</replaceable></option></arg>
114
<arg><option>--config-file=<replaceable
115
>FILE</replaceable></option></arg>
117
<arg><option>--debug</option></arg>
120
<command>&COMMANDNAME;</command>
122
<arg choice="plain"><option>--help</option></arg>
123
<arg choice="plain"><option>-?</option></arg>
127
<command>&COMMANDNAME;</command>
128
<arg choice="plain"><option>--usage</option></arg>
131
<command>&COMMANDNAME;</command>
133
<arg choice="plain"><option>--version</option></arg>
134
<arg choice="plain"><option>-V</option></arg>
100
139
<refsect1 id="description">
101
140
<title>DESCRIPTION</title>
103
<command>&COMMANDNAME;</command> is a plugin runner that waits
104
for any of its plugins to return sucessfull with a password, and
105
passes it to cryptsetup as stdout message. This command is not
106
meant to be invoked directly, but is instead meant to be run by
107
cryptsetup by being specified in /etc/crypttab as a keyscript
108
and subsequlently started in the initrd environment. See
109
<citerefentry><refentrytitle>crypttab</refentrytitle>
110
<manvolnum>5</manvolnum></citerefentry> for more information on
115
plugins is looked for in the plugins directory which by default will be
116
/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.
120
169
<title>OPTIONS</title>
123
<term><literal>-g</literal>,<literal>--global-options
124
<replaceable>OPTIONS</replaceable></literal></term>
127
Global options given to all plugins as additional start
128
arguments. Options are specified with a -o flag followed
129
by a comma separated string of options.
135
<term><literal>-o</literal>,<literal> --options-for
136
<replaceable>PLUGIN</replaceable>:<replaceable>OPTION</replaceable>
140
Plugin specific options given to the plugin as additional
141
start arguments. Options are specified with a -o flag
142
followed by a comma separated string of options.
148
<term><literal>-d</literal>,<literal> --disable
149
<replaceable>PLUGIN</replaceable>
153
Disable a specific plugin
159
<term><literal>--groupid <replaceable>ID</replaceable>
163
Group ID the plugins will run as
169
<term><literal>--userid <replaceable>ID</replaceable>
173
User ID the plugins will run as
179
<term><literal>--plugin-dir <replaceable>DIRECTORY</replaceable>
183
Specify a different plugin directory
189
<term><literal>--debug</literal></term>
198
<term><literal>-?</literal>, <literal>--help</literal></term>
207
<term><literal>--usage</literal></term>
210
Gives a short usage message
216
<term><literal>-V</literal>, <literal>--version</literal></term>
219
Prints the program version
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>.
208
<term><option>--global-options
209
<replaceable>OPTIONS</replaceable></option></term>
211
<replaceable>OPTIONS</replaceable></option></term>
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>
224
<term><option>--options-for
225
<replaceable>PLUGIN</replaceable><literal>:</literal
226
><replaceable>OPTION</replaceable></option></term>
228
<replaceable>PLUGIN</replaceable><literal>:</literal
229
><replaceable>OPTION</replaceable></option></term>
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>.
252
<term><option>--disable
253
<replaceable>PLUGIN</replaceable></option></term>
255
<replaceable>PLUGIN</replaceable></option></term>
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.
281
<term><option>--groupid
282
<replaceable>ID</replaceable></option></term>
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.
294
<term><option>--userid
295
<replaceable>ID</replaceable></option></term>
298
Change to user ID <replaceable>ID</replaceable> on
299
startup. The default is 65534. All plugins will be
300
started using this user ID. <emphasis>Note:</emphasis>
301
This must be a number, not a name.
307
<term><option>--plugin-dir
308
<replaceable>DIRECTORY</replaceable></option></term>
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.
332
<term><option>--debug</option></term>
335
Enable debug mode. This will enable a lot of output to
336
standard error about what the program is doing. The
337
program will still perform all other functions normally.
338
The default is to <emphasis>not</emphasis> run in debug
342
The plugins will <emphasis>not</emphasis> be affected by
344
<userinput><option>--global-options=--debug</option></userinput>
345
if complete debugging eruption is desired.
351
<term><option>--help</option></term>
352
<term><option>-?</option></term>
355
Gives a help message about options and their meanings.
361
<term><option>--usage</option></term>
364
Gives a short usage message.
370
<term><option>--version</option></term>
371
<term><option>-V</option></term>
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
226
420
<refsect1 id="exit_status">
227
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">
233
442
<title>FILES</title>
238
<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.