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
332
<term><option>--plugin-helper-dir
333
<replaceable>DIRECTORY</replaceable></option></term>
336
Specify a different plugin helper directory. The default
337
is <filename>/lib/mandos/plugin-helpers</filename>, which
338
will exist in the initial <acronym>RAM</acronym> disk
339
environment. (This will simply be passed to all plugins
340
via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
341
variable. See <xref linkend="writing_plugins"/>)
347
320
<term><option>--config-file
348
321
<replaceable>FILE</replaceable></option></term>
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">
551
480
<refsect1 id="bugs">
552
481
<title>BUGS</title>
554
The <option>--config-file</option> option is ignored when
555
specified from within a configuration file.
559
486
<refsect1 id="examples">
560
487
<title>EXAMPLE</title>
563
Normal invocation needs no options:
566
<userinput>&COMMANDNAME;</userinput>
571
Run the program, but not the plugins, in debug mode:
575
<!-- do not wrap this line -->
576
<userinput>&COMMANDNAME; --debug</userinput>
582
Run all plugins, but run the <quote>foo</quote> plugin in
587
<!-- do not wrap this line -->
588
<userinput>&COMMANDNAME; --options-for=foo:--debug</userinput>
594
Run all plugins, but not the program, in debug mode:
598
<!-- do not wrap this line -->
599
<userinput>&COMMANDNAME; --global-options=--debug</userinput>
605
Read a different configuration file, run plugins from a
606
different directory, specify an alternate plugin helper
607
directory and add two options to the
608
<citerefentry><refentrytitle >mandos-client</refentrytitle>
609
<manvolnum>8mandos</manvolnum></citerefentry> plugin:
613
<!-- do not wrap this line -->
614
<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>
619
492
<refsect1 id="security">
620
493
<title>SECURITY</title>
622
This program will, when starting, try to switch to another user.
623
If it is started as root, it will succeed, and will by default
624
switch to user and group 65534, which are assumed to be
625
non-privileged. This user and group is then what all plugins
626
will be started as. Therefore, the only way to run a plugin as
627
a privileged user is to have the set-user-ID or set-group-ID bit
628
set on the plugin executable file (see <citerefentry>
629
<refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
633
If this program is used as a keyscript in <citerefentry
634
><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
635
</citerefentry>, there is a slight risk that if this program
636
fails to work, there might be no way to boot the system except
637
for booting from another media and editing the initial RAM disk
638
image to not run this program. This is, however, unlikely,
639
since the <citerefentry><refentrytitle
640
>password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
641
</citerefentry> plugin will read a password from the console in
642
case of failure of the other plugins, and this plugin runner
643
will also, in case of catastrophic failure, itself fall back to
644
asking and outputting a password on the console (see <xref
645
linkend="fallback"/>).
649
498
<refsect1 id="see_also">
650
499
<title>SEE ALSO</title>
652
<citerefentry><refentrytitle>intro</refentrytitle>
653
<manvolnum>8mandos</manvolnum></citerefentry>,
654
501
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
655
502
<manvolnum>8</manvolnum></citerefentry>,
656
<citerefentry><refentrytitle>crypttab</refentrytitle>
657
<manvolnum>5</manvolnum></citerefentry>,
658
<citerefentry><refentrytitle>execve</refentrytitle>
659
<manvolnum>2</manvolnum></citerefentry>,
660
503
<citerefentry><refentrytitle>mandos</refentrytitle>
661
504
<manvolnum>8</manvolnum></citerefentry>,
662
505
<citerefentry><refentrytitle>password-prompt</refentrytitle>
663
506
<manvolnum>8mandos</manvolnum></citerefentry>,
664
<citerefentry><refentrytitle>mandos-client</refentrytitle>
507
<citerefentry><refentrytitle>password-request</refentrytitle>
665
508
<manvolnum>8mandos</manvolnum></citerefentry>