11
12
<title>Mandos Manual</title>
12
13
<!-- Nwalsh’s docbook scripts use this to generate the footer: -->
13
14
<productname>Mandos</productname>
14
<productnumber>&VERSION;</productnumber>
15
<productnumber>&version;</productnumber>
15
16
<date>&TIMESTAMP;</date>
18
19
<firstname>Björn</firstname>
19
20
<surname>Påhlsson</surname>
21
<email>belorn@fukt.bsnet.se</email>
22
<email>belorn@recompile.se</email>
25
26
<firstname>Teddy</firstname>
26
27
<surname>Hogeborn</surname>
28
<email>teddy@fukt.bsnet.se</email>
29
<email>teddy@recompile.se</email>
34
46
<holder>Teddy Hogeborn</holder>
35
47
<holder>Björn Påhlsson</holder>
37
49
<xi:include href="legalnotice.xml"/>
41
53
<refentrytitle>&COMMANDNAME;</refentrytitle>
42
54
<manvolnum>8mandos</manvolnum>
46
58
<refname><command>&COMMANDNAME;</command></refname>
48
Run Mandos plugins. Pass data from first succesful one.
60
Run Mandos plugins, pass data from first to succeed.
54
66
<command>&COMMANDNAME;</command>
55
67
<group rep="repeat">
56
68
<arg choice="plain"><option>--global-env=<replaceable
57
>VAR</replaceable><literal>=</literal><replaceable
69
>ENV</replaceable><literal>=</literal><replaceable
58
70
>value</replaceable></option></arg>
59
<arg choice="plain"><option>-e
60
<replaceable>VAR</replaceable><literal>=</literal><replaceable
71
<arg choice="plain"><option>-G
72
<replaceable>ENV</replaceable><literal>=</literal><replaceable
61
73
>value</replaceable> </option></arg>
130
155
<title>DESCRIPTION</title>
132
157
<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.
158
be specified as a <quote>keyscript</quote> for the root disk in
159
<citerefentry><refentrytitle>crypttab</refentrytitle>
160
<manvolnum>5</manvolnum></citerefentry>. The aim of this
161
program is therefore to output a password, which then
162
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
163
<manvolnum>8</manvolnum></citerefentry> will use to unlock the
142
167
This program is not meant to be invoked directly, but can be in
231
256
<option>--bar</option> with the option argument
232
257
<quote>baz</quote> is either
233
258
<userinput>--options-for=foo:--bar=baz</userinput> or
234
<userinput>--options-for=foo:--bar,baz</userinput>, but
235
<emphasis>not</emphasis>
236
<userinput>--options-for="foo:--bar baz"</userinput>.
259
<userinput>--options-for=foo:--bar,baz</userinput>. Using
260
<userinput>--options-for="foo:--bar baz"</userinput>. will
261
<emphasis>not</emphasis> work.
242
<term><option> --disable
267
<term><option>--disable
243
268
<replaceable>PLUGIN</replaceable></option></term>
245
270
<replaceable>PLUGIN</replaceable></option></term>
335
<term><option>--plugin-helper-dir
336
<replaceable>DIRECTORY</replaceable></option></term>
339
Specify a different plugin helper directory. The default
340
is <filename>/lib/mandos/plugin-helpers</filename>, which
341
will exist in the initial <acronym>RAM</acronym> disk
342
environment. (This will simply be passed to all plugins
343
via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
344
variable. See <xref linkend="writing_plugins"/>)
350
<term><option>--config-file
351
<replaceable>FILE</replaceable></option></term>
354
Specify a different file to read additional options from.
355
See <xref linkend="files"/>. Other command line options
356
will override options specified in the file.
295
362
<term><option>--debug</option></term>
356
423
<title>PLUGINS</title>
358
425
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
426
<firstterm>plugins</firstterm>, which are executable programs in
427
a directory in the initial <acronym>RAM</acronym> disk
428
environment. The default directory is
362
429
<filename>/lib/mandos/plugins.d</filename>, but this can be
363
430
changed with the <option>--plugin-dir</option> option. The
364
431
plugins are started in parallel, and the first plugin to output
366
433
code will make this plugin-runner output the password from that
367
434
plugin, stop any other plugins, and exit.
437
<refsect2 id="writing_plugins">
438
<title>WRITING PLUGINS</title>
440
A plugin is an executable program which prints a password to
441
its standard output and then exits with a successful (zero)
442
exit status. If the exit status is not zero, any output on
443
standard output will be ignored by the plugin runner. Any
444
output on its standard error channel will simply be passed to
445
the standard error of the plugin runner, usually the system
449
If the password is a single-line, manually entered passprase,
450
a final trailing newline character should
451
<emphasis>not</emphasis> be printed.
454
The plugin will run in the initial RAM disk environment, so
455
care must be taken not to depend on any files or running
456
services not available there. Any helper executables required
457
by the plugin (which are not in the <envar>PATH</envar>) can
458
be placed in the plugin helper directory, the name of which
459
will be made available to the plugin via the
460
<envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
463
The plugin must exit cleanly and free all allocated resources
464
upon getting the TERM signal, since this is what the plugin
465
runner uses to stop all other plugins when one plugin has
466
output a password and exited cleanly.
469
The plugin must not use resources, like for instance reading
470
from the standard input, without knowing that no other plugin
474
It is useful, but not required, for the plugin to take the
475
<option>--debug</option> option.
371
480
<refsect1 id="fallback">
415
530
of a line is ignored.
533
This program is meant to run in the initial RAM disk
534
environment, so that is where this file is assumed to
535
exist. The file does not need to exist in the normal
418
539
This file will be processed <emphasis>before</emphasis>
419
540
the normal command line options, so the latter can
420
541
override the former, if need be.
544
This file name is the default; the file to read for
545
arguments can be changed using the
546
<option>--config-file</option> option.
551
<term><filename class="directory"
552
>/lib/mandos/plugins.d</filename></term>
555
The default plugin directory; can be changed by the
556
<option>--plugin-dir</option> option.
561
<term><filename class="directory"
562
>/lib/mandos/plugin-helpers</filename></term>
565
The default plugin helper directory; can be changed by
566
the <option>--plugin-helper-dir</option> option.
428
574
<refsect1 id="bugs">
429
575
<title>BUGS</title>
431
There is no <option>--enable</option> option to enable disabled
577
The <option>--config-file</option> option is ignored when
578
specified from within a configuration file.
580
<xi:include href="bugs.xml"/>
436
583
<refsect1 id="examples">
437
584
<title>EXAMPLE</title>
587
Normal invocation needs no options:
590
<userinput>&COMMANDNAME;</userinput>
595
Run the program, but not the plugins, in debug mode:
599
<!-- do not wrap this line -->
600
<userinput>&COMMANDNAME; --debug</userinput>
606
Run all plugins, but run the <quote>foo</quote> plugin in
611
<!-- do not wrap this line -->
612
<userinput>&COMMANDNAME; --options-for=foo:--debug</userinput>
618
Run all plugins, but not the program, in debug mode:
622
<!-- do not wrap this line -->
623
<userinput>&COMMANDNAME; --global-options=--debug</userinput>
629
Read a different configuration file, run plugins from a
630
different directory, specify an alternate plugin helper
631
directory and add four options to the
632
<citerefentry><refentrytitle >mandos-client</refentrytitle>
633
<manvolnum>8mandos</manvolnum></citerefentry> plugin:
637
<!-- do not wrap this line -->
638
<userinput>cd /etc/keys/mandos; &COMMANDNAME; --config-file=/etc/mandos/plugin-runner.conf --plugin-dir /usr/lib/x86_64-linux-gnu/mandos/plugins.d --plugin-helper-dir /usr/lib/x86_64-linux-gnu/mandos/plugin-helpers --options-for=mandos-client:--pubkey=pubkey.txt,​--seckey=seckey.txt,​--tls-pubkey=tls-pubkey.pem,​--tls-privkey=tls-privkey.pem</userinput>
442
643
<refsect1 id="security">
443
644
<title>SECURITY</title>
646
This program will, when starting, try to switch to another user.
647
If it is started as root, it will succeed, and will by default
648
switch to user and group 65534, which are assumed to be
649
non-privileged. This user and group is then what all plugins
650
will be started as. Therefore, the only way to run a plugin as
651
a privileged user is to have the set-user-ID or set-group-ID bit
652
set on the plugin executable file (see <citerefentry>
653
<refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
657
If this program is used as a keyscript in <citerefentry
658
><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
659
</citerefentry>, there is a slight risk that if this program
660
fails to work, there might be no way to boot the system except
661
for booting from another media and editing the initial RAM disk
662
image to not run this program. This is, however, unlikely,
663
since the <citerefentry><refentrytitle
664
>password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
665
</citerefentry> plugin will read a password from the console in
666
case of failure of the other plugins, and this plugin runner
667
will also, in case of catastrophic failure, itself fall back to
668
asking and outputting a password on the console (see <xref
669
linkend="fallback"/>).
448
673
<refsect1 id="see_also">
449
674
<title>SEE ALSO</title>
676
<citerefentry><refentrytitle>intro</refentrytitle>
677
<manvolnum>8mandos</manvolnum></citerefentry>,
451
678
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
452
679
<manvolnum>8</manvolnum></citerefentry>,
680
<citerefentry><refentrytitle>crypttab</refentrytitle>
681
<manvolnum>5</manvolnum></citerefentry>,
682
<citerefentry><refentrytitle>execve</refentrytitle>
683
<manvolnum>2</manvolnum></citerefentry>,
453
684
<citerefentry><refentrytitle>mandos</refentrytitle>
454
685
<manvolnum>8</manvolnum></citerefentry>,
455
686
<citerefentry><refentrytitle>password-prompt</refentrytitle>
456
687
<manvolnum>8mandos</manvolnum></citerefentry>,
457
<citerefentry><refentrytitle>password-request</refentrytitle>
688
<citerefentry><refentrytitle>mandos-client</refentrytitle>
458
689
<manvolnum>8mandos</manvolnum></citerefentry>
added
removed
plugin-runner.xml
