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
71
<arg choice="plain"><option>-G
60
<replaceable>VAR</replaceable><literal>=</literal><replaceable
72
<replaceable>ENV</replaceable><literal>=</literal><replaceable
61
73
>value</replaceable> </option></arg>
140
155
<title>DESCRIPTION</title>
142
157
<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.
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
152
167
This program is not meant to be invoked directly, but can be in
393
423
<title>PLUGINS</title>
395
425
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
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
399
429
<filename>/lib/mandos/plugins.d</filename>, but this can be
400
430
changed with the <option>--plugin-dir</option> option. The
401
431
plugins are started in parallel, and the first plugin to output
403
433
code will make this plugin-runner output the password from that
404
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.
408
480
<refsect1 id="fallback">
480
574
<refsect1 id="bugs">
481
575
<title>BUGS</title>
577
The <option>--config-file</option> option is ignored when
578
specified from within a configuration file.
580
<xi:include href="bugs.xml"/>
486
583
<refsect1 id="examples">
487
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>
492
643
<refsect1 id="security">
493
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"/>).
498
673
<refsect1 id="see_also">
499
674
<title>SEE ALSO</title>
676
<citerefentry><refentrytitle>intro</refentrytitle>
677
<manvolnum>8mandos</manvolnum></citerefentry>,
501
678
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
502
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>,
503
684
<citerefentry><refentrytitle>mandos</refentrytitle>
504
685
<manvolnum>8</manvolnum></citerefentry>,
505
686
<citerefentry><refentrytitle>password-prompt</refentrytitle>
506
687
<manvolnum>8mandos</manvolnum></citerefentry>,
507
<citerefentry><refentrytitle>password-request</refentrytitle>
688
<citerefentry><refentrytitle>mandos-client</refentrytitle>
508
689
<manvolnum>8mandos</manvolnum></citerefentry>
added
removed
plugin-runner.xml
