/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-06">
 
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>
423
451
      <para>
424
452
        The plugin will run in the initial RAM disk environment, so
425
453
        care must be taken not to depend on any files or running
426
 
        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.
427
459
      </para>
428
460
      <para>
429
461
        The plugin must exit cleanly and free all allocated resources
472
504
      only passes on its environment to all the plugins.  The
473
505
      environment passed to plugins can be modified using the
474
506
      <option>--global-env</option> and <option>--env-for</option>
475
 
      options.
 
507
      options.  Also, the <option>--plugin-helper-dir</option> option
 
508
      will affect the environment variable
 
509
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
476
510
    </para>
477
511
  </refsect1>
478
512
  
511
545
            </para>
512
546
          </listitem>
513
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>
514
568
      </variablelist>
515
569
    </para>
516
570
  </refsect1>
521
575
      The <option>--config-file</option> option is ignored when
522
576
      specified from within a configuration file.
523
577
    </para>
 
578
    <xi:include href="bugs.xml"/>
524
579
  </refsect1>
525
580
  
526
581
  <refsect1 id="examples">
569
624
    </informalexample>
570
625
    <informalexample>
571
626
      <para>
572
 
        Run plugins from a different directory, read a different
573
 
        configuration file, and add two options to the
 
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
574
630
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
575
631
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
576
632
      </para>
577
633
      <para>
578
634
 
579
635
<!-- do not wrap this line -->
580
 
<userinput>&COMMANDNAME;  --config-file=/etc/mandos/plugin-runner.conf --plugin-dir /usr/lib/mandos/plugins.d --options-for=mandos-client:--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>
581
637
 
582
638
      </para>
583
639
    </informalexample>
615
671
  <refsect1 id="see_also">
616
672
    <title>SEE ALSO</title>
617
673
    <para>
 
674
      <citerefentry><refentrytitle>intro</refentrytitle>
 
675
      <manvolnum>8mandos</manvolnum></citerefentry>,
618
676
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
619
677
      <manvolnum>8</manvolnum></citerefentry>,
620
678
      <citerefentry><refentrytitle>crypttab</refentrytitle>