12
11
<title>Mandos Manual</title>
13
12
<!-- Nwalsh’s docbook scripts use this to generate the footer: -->
14
13
<productname>Mandos</productname>
15
<productnumber>&version;</productnumber>
14
<productnumber>&VERSION;</productnumber>
16
15
<date>&TIMESTAMP;</date>
19
18
<firstname>Björn</firstname>
20
19
<surname>Påhlsson</surname>
22
<email>belorn@recompile.se</email>
21
<email>belorn@fukt.bsnet.se</email>
26
25
<firstname>Teddy</firstname>
27
26
<surname>Hogeborn</surname>
29
<email>teddy@recompile.se</email>
28
<email>teddy@fukt.bsnet.se</email>
43
34
<holder>Teddy Hogeborn</holder>
44
35
<holder>Björn Påhlsson</holder>
46
37
<xi:include href="legalnotice.xml"/>
50
41
<refentrytitle>&COMMANDNAME;</refentrytitle>
51
42
<manvolnum>8mandos</manvolnum>
55
46
<refname><command>&COMMANDNAME;</command></refname>
57
Run Mandos plugins, pass data from first to succeed.
48
Run Mandos plugins. Pass data from first succesful one.
63
54
<command>&COMMANDNAME;</command>
64
55
<group rep="repeat">
65
56
<arg choice="plain"><option>--global-env=<replaceable
66
>ENV</replaceable><literal>=</literal><replaceable
57
>VAR</replaceable><literal>=</literal><replaceable
67
58
>value</replaceable></option></arg>
68
59
<arg choice="plain"><option>-G
69
<replaceable>ENV</replaceable><literal>=</literal><replaceable
60
<replaceable>VAR</replaceable><literal>=</literal><replaceable
70
61
>value</replaceable> </option></arg>
152
140
<title>DESCRIPTION</title>
154
142
<command>&COMMANDNAME;</command> is a program which is meant to
155
be specified as a <quote>keyscript</quote> for the root disk in
156
<citerefentry><refentrytitle>crypttab</refentrytitle>
157
<manvolnum>5</manvolnum></citerefentry>. The aim of this
158
program is therefore to output a password, which then
159
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
160
<manvolnum>8</manvolnum></citerefentry> will use to unlock the
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.
164
152
This program is not meant to be invoked directly, but can be in
430
403
code will make this plugin-runner output the password from that
431
404
plugin, stop any other plugins, and exit.
434
<refsect2 id="writing_plugins">
435
<title>WRITING PLUGINS</title>
437
A plugin is simply a program which prints a password to its
438
standard output and then exits with a successful (zero) exit
439
status. If the exit status is not zero, any output on
440
standard output will be ignored by the plugin runner. Any
441
output on its standard error channel will simply be passed to
442
the standard error of the plugin runner, usually the system
446
If the password is a single-line, manually entered passprase,
447
a final trailing newline character should
448
<emphasis>not</emphasis> be printed.
451
The plugin will run in the initial RAM disk environment, so
452
care must be taken not to depend on any files or running
453
services not available there. Any helper executables required
454
by the plugin (which are not in the <envar>PATH</envar>) can
455
be placed in the plugin helper directory, the name of which
456
will be made available to the plugin via the
457
<envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
460
The plugin must exit cleanly and free all allocated resources
461
upon getting the TERM signal, since this is what the plugin
462
runner uses to stop all other plugins when one plugin has
463
output a password and exited cleanly.
466
The plugin must not use resources, like for instance reading
467
from the standard input, without knowing that no other plugin
471
It is useful, but not required, for the plugin to take the
472
<option>--debug</option> option.
477
408
<refsect1 id="fallback">
571
480
<refsect1 id="bugs">
572
481
<title>BUGS</title>
574
The <option>--config-file</option> option is ignored when
575
specified from within a configuration file.
577
<xi:include href="bugs.xml"/>
580
486
<refsect1 id="examples">
581
487
<title>EXAMPLE</title>
584
Normal invocation needs no options:
587
<userinput>&COMMANDNAME;</userinput>
592
Run the program, but not the plugins, in debug mode:
596
<!-- do not wrap this line -->
597
<userinput>&COMMANDNAME; --debug</userinput>
603
Run all plugins, but run the <quote>foo</quote> plugin in
608
<!-- do not wrap this line -->
609
<userinput>&COMMANDNAME; --options-for=foo:--debug</userinput>
615
Run all plugins, but not the program, in debug mode:
619
<!-- do not wrap this line -->
620
<userinput>&COMMANDNAME; --global-options=--debug</userinput>
626
Read a different configuration file, run plugins from a
627
different directory, specify an alternate plugin helper
628
directory and add two options to the
629
<citerefentry><refentrytitle >mandos-client</refentrytitle>
630
<manvolnum>8mandos</manvolnum></citerefentry> plugin:
634
<!-- do not wrap this line -->
635
<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</userinput>
640
492
<refsect1 id="security">
641
493
<title>SECURITY</title>
643
This program will, when starting, try to switch to another user.
644
If it is started as root, it will succeed, and will by default
645
switch to user and group 65534, which are assumed to be
646
non-privileged. This user and group is then what all plugins
647
will be started as. Therefore, the only way to run a plugin as
648
a privileged user is to have the set-user-ID or set-group-ID bit
649
set on the plugin executable file (see <citerefentry>
650
<refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
654
If this program is used as a keyscript in <citerefentry
655
><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
656
</citerefentry>, there is a slight risk that if this program
657
fails to work, there might be no way to boot the system except
658
for booting from another media and editing the initial RAM disk
659
image to not run this program. This is, however, unlikely,
660
since the <citerefentry><refentrytitle
661
>password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
662
</citerefentry> plugin will read a password from the console in
663
case of failure of the other plugins, and this plugin runner
664
will also, in case of catastrophic failure, itself fall back to
665
asking and outputting a password on the console (see <xref
666
linkend="fallback"/>).
670
498
<refsect1 id="see_also">
671
499
<title>SEE ALSO</title>
673
<citerefentry><refentrytitle>intro</refentrytitle>
674
<manvolnum>8mandos</manvolnum></citerefentry>,
675
501
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
676
502
<manvolnum>8</manvolnum></citerefentry>,
677
<citerefentry><refentrytitle>crypttab</refentrytitle>
678
<manvolnum>5</manvolnum></citerefentry>,
679
<citerefentry><refentrytitle>execve</refentrytitle>
680
<manvolnum>2</manvolnum></citerefentry>,
681
503
<citerefentry><refentrytitle>mandos</refentrytitle>
682
504
<manvolnum>8</manvolnum></citerefentry>,
683
505
<citerefentry><refentrytitle>password-prompt</refentrytitle>
684
506
<manvolnum>8mandos</manvolnum></citerefentry>,
685
<citerefentry><refentrytitle>mandos-client</refentrytitle>
507
<citerefentry><refentrytitle>password-request</refentrytitle>
686
508
<manvolnum>8mandos</manvolnum></citerefentry>