/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

Viewing changes to plugin-runner.xml

  • Committer: Teddy Hogeborn
  • Date: 2017-08-20 13:50:57 UTC
  • Revision ID: teddy@recompile.se-20170820135057-u069yh7hhk2ha1a2
Don't import doctest module in mandos-ctl unless running tests.

* mandos-ctl: Don't import doctest module unless running tests.

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugin-runner.xml
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-05">
 
5
<!ENTITY TIMESTAMP "2017-02-23">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
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>
16
17
    <authorgroup>
17
18
      <author>
18
19
        <firstname>Björn</firstname>
19
20
        <surname>Påhlsson</surname>
20
21
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
22
23
        </address>
23
24
      </author>
24
25
      <author>
25
26
        <firstname>Teddy</firstname>
26
27
        <surname>Hogeborn</surname>
27
28
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
29
30
        </address>
30
31
      </author>
31
32
    </authorgroup>
32
33
    <copyright>
33
34
      <year>2008</year>
 
35
      <year>2009</year>
 
36
      <year>2010</year>
 
37
      <year>2011</year>
 
38
      <year>2012</year>
 
39
      <year>2013</year>
 
40
      <year>2014</year>
 
41
      <year>2015</year>
 
42
      <year>2016</year>
 
43
      <year>2017</year>
34
44
      <holder>Teddy Hogeborn</holder>
35
45
      <holder>Björn Påhlsson</holder>
36
46
    </copyright>
37
47
    <xi:include href="legalnotice.xml"/>
38
48
  </refentryinfo>
39
 
 
 
49
  
40
50
  <refmeta>
41
51
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
52
    <manvolnum>8mandos</manvolnum>
48
58
      Run Mandos plugins, pass data from first to succeed.
49
59
    </refpurpose>
50
60
  </refnamediv>
51
 
 
 
61
  
52
62
  <refsynopsisdiv>
53
63
    <cmdsynopsis>
54
64
      <command>&COMMANDNAME;</command>
55
65
      <group rep="repeat">
56
66
        <arg choice="plain"><option>--global-env=<replaceable
57
 
        >VAR</replaceable><literal>=</literal><replaceable
 
67
        >ENV</replaceable><literal>=</literal><replaceable
58
68
        >value</replaceable></option></arg>
59
69
        <arg choice="plain"><option>-G
60
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
70
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
61
71
        >value</replaceable> </option></arg>
62
72
      </group>
63
73
      <sbr/>
111
121
      <arg><option>--plugin-dir=<replaceable
112
122
      >DIRECTORY</replaceable></option></arg>
113
123
      <sbr/>
 
124
      <arg><option>--plugin-helper-dir=<replaceable
 
125
      >DIRECTORY</replaceable></option></arg>
 
126
      <sbr/>
114
127
      <arg><option>--config-file=<replaceable
115
128
      >FILE</replaceable></option></arg>
116
129
      <sbr/>
170
183
    <variablelist>
171
184
      <varlistentry>
172
185
        <term><option>--global-env
173
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
186
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
174
187
        >value</replaceable></option></term>
175
188
        <term><option>-G
176
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
189
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
177
190
        >value</replaceable></option></term>
178
191
        <listitem>
179
192
          <para>
247
260
          </para>
248
261
        </listitem>
249
262
      </varlistentry>
250
 
 
 
263
      
251
264
      <varlistentry>
252
265
        <term><option>--disable
253
266
        <replaceable>PLUGIN</replaceable></option></term>
258
271
            Disable the plugin named
259
272
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
260
273
            started.
261
 
          </para>       
 
274
          </para>
262
275
        </listitem>
263
276
      </varlistentry>
264
 
 
 
277
      
265
278
      <varlistentry>
266
279
        <term><option>--enable
267
280
        <replaceable>PLUGIN</replaceable></option></term>
276
289
          </para>
277
290
        </listitem>
278
291
      </varlistentry>
279
 
 
 
292
      
280
293
      <varlistentry>
281
294
        <term><option>--groupid
282
295
        <replaceable>ID</replaceable></option></term>
289
302
          </para>
290
303
        </listitem>
291
304
      </varlistentry>
292
 
 
 
305
      
293
306
      <varlistentry>
294
307
        <term><option>--userid
295
308
        <replaceable>ID</replaceable></option></term>
302
315
          </para>
303
316
        </listitem>
304
317
      </varlistentry>
305
 
 
 
318
      
306
319
      <varlistentry>
307
320
        <term><option>--plugin-dir
308
321
        <replaceable>DIRECTORY</replaceable></option></term>
317
330
      </varlistentry>
318
331
      
319
332
      <varlistentry>
 
333
        <term><option>--plugin-helper-dir
 
334
        <replaceable>DIRECTORY</replaceable></option></term>
 
335
        <listitem>
 
336
          <para>
 
337
            Specify a different plugin helper directory.  The default
 
338
            is <filename>/lib/mandos/plugin-helpers</filename>, which
 
339
            will exist in the initial <acronym>RAM</acronym> disk
 
340
            environment.  (This will simply be passed to all plugins
 
341
            via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
 
342
            variable.  See <xref linkend="writing_plugins"/>)
 
343
          </para>
 
344
        </listitem>
 
345
      </varlistentry>
 
346
      
 
347
      <varlistentry>
320
348
        <term><option>--config-file
321
349
        <replaceable>FILE</replaceable></option></term>
322
350
        <listitem>
365
393
          </para>
366
394
        </listitem>
367
395
      </varlistentry>
368
 
 
 
396
      
369
397
      <varlistentry>
370
398
        <term><option>--version</option></term>
371
399
        <term><option>-V</option></term>
377
405
      </varlistentry>
378
406
    </variablelist>
379
407
  </refsect1>
380
 
 
 
408
  
381
409
  <refsect1 id="overview">
382
410
    <title>OVERVIEW</title>
383
411
    <xi:include href="overview.xml"/>
403
431
      code will make this plugin-runner output the password from that
404
432
      plugin, stop any other plugins, and exit.
405
433
    </para>
406
 
 
 
434
    
407
435
    <refsect2 id="writing_plugins">
408
436
      <title>WRITING PLUGINS</title>
409
437
      <para>
416
444
        console.
417
445
      </para>
418
446
      <para>
 
447
        If the password is a single-line, manually entered passprase,
 
448
        a final trailing newline character should
 
449
        <emphasis>not</emphasis> be printed.
 
450
      </para>
 
451
      <para>
419
452
        The plugin will run in the initial RAM disk environment, so
420
453
        care must be taken not to depend on any files or running
421
 
        services not available there.
 
454
        services not available there.  Any helper executables required
 
455
        by the plugin (which are not in the <envar>PATH</envar>) can
 
456
        be placed in the plugin helper directory, the name of which
 
457
        will be made available to the plugin via the
 
458
        <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
422
459
      </para>
423
460
      <para>
424
461
        The plugin must exit cleanly and free all allocated resources
467
504
      only passes on its environment to all the plugins.  The
468
505
      environment passed to plugins can be modified using the
469
506
      <option>--global-env</option> and <option>--env-for</option>
470
 
      options.
 
507
      options.  Also, the <option>--plugin-helper-dir</option> option
 
508
      will affect the environment variable
 
509
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
471
510
    </para>
472
511
  </refsect1>
473
512
  
506
545
            </para>
507
546
          </listitem>
508
547
        </varlistentry>
 
548
        <varlistentry>
 
549
          <term><filename class="directory"
 
550
          >/lib/mandos/plugins.d</filename></term>
 
551
          <listitem>
 
552
            <para>
 
553
              The default plugin directory; can be changed by the
 
554
              <option>--plugin-dir</option> option.
 
555
            </para>
 
556
          </listitem>
 
557
        </varlistentry>
 
558
        <varlistentry>
 
559
          <term><filename class="directory"
 
560
          >/lib/mandos/plugin-helpers</filename></term>
 
561
          <listitem>
 
562
            <para>
 
563
              The default plugin helper directory; can be changed by
 
564
              the <option>--plugin-helper-dir</option> option.
 
565
            </para>
 
566
          </listitem>
 
567
        </varlistentry>
509
568
      </variablelist>
510
569
    </para>
511
570
  </refsect1>
516
575
      The <option>--config-file</option> option is ignored when
517
576
      specified from within a configuration file.
518
577
    </para>
 
578
    <xi:include href="bugs.xml"/>
519
579
  </refsect1>
520
580
  
521
581
  <refsect1 id="examples">
564
624
    </informalexample>
565
625
    <informalexample>
566
626
      <para>
567
 
        Run plugins from a different directory, read a different
568
 
        configuration file, and add two options to the
569
 
        <citerefentry><refentrytitle >password-request</refentrytitle>
 
627
        Read a different configuration file, run plugins from a
 
628
        different directory, specify an alternate plugin helper
 
629
        directory and add two options to the
 
630
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
570
631
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
571
632
      </para>
572
633
      <para>
573
634
 
574
635
<!-- do not wrap this line -->
575
 
<userinput>&COMMANDNAME;  --config-file=/etc/mandos/plugin-runner.conf --plugin-dir /usr/lib/mandos/plugins.d --options-for=password-request:--pubkey=/etc/keys/mandos/pubkey.txt,--seckey=/etc/keys/mandos/seckey.txt</userinput>
 
636
<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>
576
637
 
577
638
      </para>
578
639
    </informalexample>
586
647
      non-privileged.  This user and group is then what all plugins
587
648
      will be started as.  Therefore, the only way to run a plugin as
588
649
      a privileged user is to have the set-user-ID or set-group-ID bit
589
 
      set on the plugin executable files (see <citerefentry>
 
650
      set on the plugin executable file (see <citerefentry>
590
651
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
591
652
      </citerefentry>).
592
653
    </para>
610
671
  <refsect1 id="see_also">
611
672
    <title>SEE ALSO</title>
612
673
    <para>
 
674
      <citerefentry><refentrytitle>intro</refentrytitle>
 
675
      <manvolnum>8mandos</manvolnum></citerefentry>,
613
676
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
614
677
      <manvolnum>8</manvolnum></citerefentry>,
615
678
      <citerefentry><refentrytitle>crypttab</refentrytitle>
620
683
      <manvolnum>8</manvolnum></citerefentry>,
621
684
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
622
685
      <manvolnum>8mandos</manvolnum></citerefentry>,
623
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
686
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
624
687
      <manvolnum>8mandos</manvolnum></citerefentry>
625
688
    </para>
626
689
  </refsect1>