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">
4
5
<!ENTITY COMMANDNAME "plugin-runner">
5
<!ENTITY TIMESTAMP "2023-04-30">
6
<!ENTITY % common SYSTEM "common.ent">
6
<!ENTITY TIMESTAMP "2008-09-04">
10
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
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>
46
34
<holder>Teddy Hogeborn</holder>
47
35
<holder>Björn Påhlsson</holder>
49
37
<xi:include href="legalnotice.xml"/>
53
41
<refentrytitle>&COMMANDNAME;</refentrytitle>
54
42
<manvolnum>8mandos</manvolnum>
60
48
Run Mandos plugins, pass data from first to succeed.
66
54
<command>&COMMANDNAME;</command>
67
55
<group rep="repeat">
68
56
<arg choice="plain"><option>--global-env=<replaceable
69
>ENV</replaceable><literal>=</literal><replaceable
57
>VAR</replaceable><literal>=</literal><replaceable
70
58
>value</replaceable></option></arg>
71
59
<arg choice="plain"><option>-G
72
<replaceable>ENV</replaceable><literal>=</literal><replaceable
60
<replaceable>VAR</replaceable><literal>=</literal><replaceable
73
61
>value</replaceable> </option></arg>
123
111
<arg><option>--plugin-dir=<replaceable
124
112
>DIRECTORY</replaceable></option></arg>
126
<arg><option>--plugin-helper-dir=<replaceable
127
>DIRECTORY</replaceable></option></arg>
129
114
<arg><option>--config-file=<replaceable
130
115
>FILE</replaceable></option></arg>
187
172
<term><option>--global-env
188
<replaceable>ENV</replaceable><literal>=</literal><replaceable
173
<replaceable>VAR</replaceable><literal>=</literal><replaceable
189
174
>value</replaceable></option></term>
191
<replaceable>ENV</replaceable><literal>=</literal><replaceable
176
<replaceable>VAR</replaceable><literal>=</literal><replaceable
192
177
>value</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
320
<term><option>--config-file
351
321
<replaceable>FILE</replaceable></option></term>
423
393
<title>PLUGINS</title>
425
395
This program will get a password by running a number of
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
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
429
399
<filename>/lib/mandos/plugins.d</filename>, but this can be
430
400
changed with the <option>--plugin-dir</option> option. The
431
401
plugins are started in parallel, and the first plugin to output
433
403
code will make this plugin-runner output the password from that
434
404
plugin, stop any other plugins, and exit.
437
407
<refsect2 id="writing_plugins">
438
408
<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
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
443
413
standard output will be ignored by the plugin runner. Any
444
414
output on its standard error channel will simply be passed to
445
415
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
419
The plugin will run in the initial RAM disk environment, so
455
420
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.
421
services not available there.
463
424
The plugin must exit cleanly and free all allocated resources
506
467
only passes on its environment to all the plugins. The
507
468
environment passed to plugins can be modified using the
508
469
<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.
626
564
</informalexample>
627
565
<informalexample>
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>
567
Run plugins from a different directory and add two
568
options to the <citerefentry><refentrytitle
569
>password-request</refentrytitle>
633
570
<manvolnum>8mandos</manvolnum></citerefentry> plugin:
637
574
<!-- 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>
575
<userinput>&COMMANDNAME; --plugin-dir=plugins.d --options-for=password-request:--pubkey=keydir/pubkey.txt,--seckey=keydir/seckey.txt</userinput>
641
578
</informalexample>
649
586
non-privileged. This user and group is then what all plugins
650
587
will be started as. Therefore, the only way to run a plugin as
651
588
a privileged user is to have the set-user-ID or set-group-ID bit
652
set on the plugin executable file (see <citerefentry>
589
set on the plugin executable files (see <citerefentry>
653
590
<refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
654
591
</citerefentry>).
673
610
<refsect1 id="see_also">
674
611
<title>SEE ALSO</title>
676
<citerefentry><refentrytitle>intro</refentrytitle>
677
<manvolnum>8mandos</manvolnum></citerefentry>,
678
613
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
679
614
<manvolnum>8</manvolnum></citerefentry>,
680
615
<citerefentry><refentrytitle>crypttab</refentrytitle>
685
620
<manvolnum>8</manvolnum></citerefentry>,
686
621
<citerefentry><refentrytitle>password-prompt</refentrytitle>
687
622
<manvolnum>8mandos</manvolnum></citerefentry>,
688
<citerefentry><refentrytitle>mandos-client</refentrytitle>
623
<citerefentry><refentrytitle>password-request</refentrytitle>
689
624
<manvolnum>8mandos</manvolnum></citerefentry>
added
removed
plugin-runner.xml
