1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "plugin-runner">
6
<!ENTITY TIMESTAMP "2008-09-02">
5
<!ENTITY TIMESTAMP "2023-04-30">
6
<!ENTITY % common SYSTEM "common.ent">
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
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>
111
123
<arg><option>--plugin-dir=<replaceable
112
124
>DIRECTORY</replaceable></option></arg>
126
<arg><option>--plugin-helper-dir=<replaceable
127
>DIRECTORY</replaceable></option></arg>
114
129
<arg><option>--config-file=<replaceable
115
130
>FILE</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>
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>
148
163
<manvolnum>8</manvolnum></citerefentry> will use to unlock the
172
187
<term><option>--global-env
173
<replaceable>VAR</replaceable><literal>=</literal><replaceable
188
<replaceable>ENV</replaceable><literal>=</literal><replaceable
174
189
>value</replaceable></option></term>
176
<replaceable>VAR</replaceable><literal>=</literal><replaceable
191
<replaceable>ENV</replaceable><literal>=</literal><replaceable
177
192
>value</replaceable></option></term>
272
287
Re-enable the plugin named
273
288
<replaceable>PLUGIN</replaceable>. This is only useful to
274
289
undo a previous <option>--disable</option> option, maybe
275
from the config file.
290
from the configuration file.
281
296
<term><option>--groupid
282
297
<replaceable>ID</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"/>)
320
350
<term><option>--config-file
321
351
<replaceable>FILE</replaceable></option></term>
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.
407
437
<refsect2 id="writing_plugins">
408
438
<title>WRITING PLUGINS</title>
410
A plugin is simply a program which prints a password to its
411
standard output and then exits with a successful (zero) exit
412
status. If the exit status is not zero, any output on
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
413
443
standard output will be ignored by the plugin runner. Any
414
444
output on its standard error channel will simply be passed to
415
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.
419
454
The plugin will run in the initial RAM disk environment, so
420
455
care must be taken not to depend on any files or running
421
services not available there.
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.
424
463
The plugin must exit cleanly and free all allocated resources
430
469
The plugin must not use resources, like for instance reading
431
from the standard input, without knowing that no other plugins
470
from the standard input, without knowing that no other plugin
435
474
It is useful, but not required, for the plugin to take the
467
506
only passes on its environment to all the plugins. The
468
507
environment passed to plugins can be modified using the
469
508
<option>--global-env</option> and <option>--env-for</option>
509
options. Also, the <option>--plugin-helper-dir</option> option
510
will affect the environment variable
511
<envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
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.
513
<!-- <refsect1 id="bugs"> -->
514
<!-- <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"/>
519
583
<refsect1 id="examples">
520
584
<title>EXAMPLE</title>
562
626
</informalexample>
563
627
<informalexample>
565
Run plugins from a different directory and add a special
566
option to the <citerefentry><refentrytitle
567
>password-request</refentrytitle>
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>
568
633
<manvolnum>8mandos</manvolnum></citerefentry> plugin:
572
637
<!-- do not wrap this line -->
573
<userinput>&COMMANDNAME; --plugin-dir=plugins.d --options-for=password-request:--keydir=keydir</userinput>
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>
576
641
</informalexample>
584
649
non-privileged. This user and group is then what all plugins
585
650
will be started as. Therefore, the only way to run a plugin as
586
651
a privileged user is to have the set-user-ID or set-group-ID bit
587
set on the plugin executable files (see <citerefentry>
652
set on the plugin executable file (see <citerefentry>
588
653
<refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
589
654
</citerefentry>).
592
657
If this program is used as a keyscript in <citerefentry
593
658
><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
594
</citerefentry>, there is a risk that if this program fails to
595
work, there might be no way to boot the system except for
596
booting from another media and editing the initial RAM disk
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
597
662
image to not run this program. This is, however, unlikely,
598
663
since the <citerefentry><refentrytitle
599
664
>password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
608
673
<refsect1 id="see_also">
609
674
<title>SEE ALSO</title>
676
<citerefentry><refentrytitle>intro</refentrytitle>
677
<manvolnum>8mandos</manvolnum></citerefentry>,
611
678
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
612
679
<manvolnum>8</manvolnum></citerefentry>,
613
680
<citerefentry><refentrytitle>crypttab</refentrytitle>
618
685
<manvolnum>8</manvolnum></citerefentry>,
619
686
<citerefentry><refentrytitle>password-prompt</refentrytitle>
620
687
<manvolnum>8mandos</manvolnum></citerefentry>,
621
<citerefentry><refentrytitle>password-request</refentrytitle>
688
<citerefentry><refentrytitle>mandos-client</refentrytitle>
622
689
<manvolnum>8mandos</manvolnum></citerefentry>
added
removed
plugin-runner.xml
