/mandos/release

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

« back to all changes in this revision

Viewing changes to plugin-runner.xml

merge

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">
4
5
<!ENTITY COMMANDNAME "plugin-runner">
5
 
<!ENTITY TIMESTAMP "2017-02-23">
6
 
<!ENTITY % common SYSTEM "common.ent">
7
 
%common;
 
6
<!ENTITY TIMESTAMP "2008-09-06">
8
7
]>
9
8
 
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>
17
16
    <authorgroup>
18
17
      <author>
19
18
        <firstname>Björn</firstname>
20
19
        <surname>Påhlsson</surname>
21
20
        <address>
22
 
          <email>belorn@recompile.se</email>
 
21
          <email>belorn@fukt.bsnet.se</email>
23
22
        </address>
24
23
      </author>
25
24
      <author>
26
25
        <firstname>Teddy</firstname>
27
26
        <surname>Hogeborn</surname>
28
27
        <address>
29
 
          <email>teddy@recompile.se</email>
 
28
          <email>teddy@fukt.bsnet.se</email>
30
29
        </address>
31
30
      </author>
32
31
    </authorgroup>
33
32
    <copyright>
34
33
      <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>
44
34
      <holder>Teddy Hogeborn</holder>
45
35
      <holder>Björn Påhlsson</holder>
46
36
    </copyright>
47
37
    <xi:include href="legalnotice.xml"/>
48
38
  </refentryinfo>
49
 
  
 
39
 
50
40
  <refmeta>
51
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
52
42
    <manvolnum>8mandos</manvolnum>
58
48
      Run Mandos plugins, pass data from first to succeed.
59
49
    </refpurpose>
60
50
  </refnamediv>
61
 
  
 
51
 
62
52
  <refsynopsisdiv>
63
53
    <cmdsynopsis>
64
54
      <command>&COMMANDNAME;</command>
65
55
      <group rep="repeat">
66
56
        <arg choice="plain"><option>--global-env=<replaceable
67
 
        >ENV</replaceable><literal>=</literal><replaceable
 
57
        >VAR</replaceable><literal>=</literal><replaceable
68
58
        >value</replaceable></option></arg>
69
59
        <arg choice="plain"><option>-G
70
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
60
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
71
61
        >value</replaceable> </option></arg>
72
62
      </group>
73
63
      <sbr/>
121
111
      <arg><option>--plugin-dir=<replaceable
122
112
      >DIRECTORY</replaceable></option></arg>
123
113
      <sbr/>
124
 
      <arg><option>--plugin-helper-dir=<replaceable
125
 
      >DIRECTORY</replaceable></option></arg>
126
 
      <sbr/>
127
114
      <arg><option>--config-file=<replaceable
128
115
      >FILE</replaceable></option></arg>
129
116
      <sbr/>
183
170
    <variablelist>
184
171
      <varlistentry>
185
172
        <term><option>--global-env
186
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
173
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
187
174
        >value</replaceable></option></term>
188
175
        <term><option>-G
189
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
176
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
190
177
        >value</replaceable></option></term>
191
178
        <listitem>
192
179
          <para>
260
247
          </para>
261
248
        </listitem>
262
249
      </varlistentry>
263
 
      
 
250
 
264
251
      <varlistentry>
265
252
        <term><option>--disable
266
253
        <replaceable>PLUGIN</replaceable></option></term>
271
258
            Disable the plugin named
272
259
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
273
260
            started.
274
 
          </para>
 
261
          </para>       
275
262
        </listitem>
276
263
      </varlistentry>
277
 
      
 
264
 
278
265
      <varlistentry>
279
266
        <term><option>--enable
280
267
        <replaceable>PLUGIN</replaceable></option></term>
289
276
          </para>
290
277
        </listitem>
291
278
      </varlistentry>
292
 
      
 
279
 
293
280
      <varlistentry>
294
281
        <term><option>--groupid
295
282
        <replaceable>ID</replaceable></option></term>
302
289
          </para>
303
290
        </listitem>
304
291
      </varlistentry>
305
 
      
 
292
 
306
293
      <varlistentry>
307
294
        <term><option>--userid
308
295
        <replaceable>ID</replaceable></option></term>
315
302
          </para>
316
303
        </listitem>
317
304
      </varlistentry>
318
 
      
 
305
 
319
306
      <varlistentry>
320
307
        <term><option>--plugin-dir
321
308
        <replaceable>DIRECTORY</replaceable></option></term>
330
317
      </varlistentry>
331
318
      
332
319
      <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>
348
320
        <term><option>--config-file
349
321
        <replaceable>FILE</replaceable></option></term>
350
322
        <listitem>
393
365
          </para>
394
366
        </listitem>
395
367
      </varlistentry>
396
 
      
 
368
 
397
369
      <varlistentry>
398
370
        <term><option>--version</option></term>
399
371
        <term><option>-V</option></term>
405
377
      </varlistentry>
406
378
    </variablelist>
407
379
  </refsect1>
408
 
  
 
380
 
409
381
  <refsect1 id="overview">
410
382
    <title>OVERVIEW</title>
411
383
    <xi:include href="overview.xml"/>
431
403
      code will make this plugin-runner output the password from that
432
404
      plugin, stop any other plugins, and exit.
433
405
    </para>
434
 
    
 
406
 
435
407
    <refsect2 id="writing_plugins">
436
408
      <title>WRITING PLUGINS</title>
437
409
      <para>
451
423
      <para>
452
424
        The plugin will run in the initial RAM disk environment, so
453
425
        care must be taken not to depend on any files or running
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.
 
426
        services not available there.
459
427
      </para>
460
428
      <para>
461
429
        The plugin must exit cleanly and free all allocated resources
504
472
      only passes on its environment to all the plugins.  The
505
473
      environment passed to plugins can be modified using the
506
474
      <option>--global-env</option> and <option>--env-for</option>
507
 
      options.  Also, the <option>--plugin-helper-dir</option> option
508
 
      will affect the environment variable
509
 
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
 
475
      options.
510
476
    </para>
511
477
  </refsect1>
512
478
  
545
511
            </para>
546
512
          </listitem>
547
513
        </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>
568
514
      </variablelist>
569
515
    </para>
570
516
  </refsect1>
575
521
      The <option>--config-file</option> option is ignored when
576
522
      specified from within a configuration file.
577
523
    </para>
578
 
    <xi:include href="bugs.xml"/>
579
524
  </refsect1>
580
525
  
581
526
  <refsect1 id="examples">
624
569
    </informalexample>
625
570
    <informalexample>
626
571
      <para>
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
 
572
        Run plugins from a different directory, read a different
 
573
        configuration file, and add two options to the
630
574
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
631
575
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
632
576
      </para>
633
577
      <para>
634
578
 
635
579
<!-- do not wrap this line -->
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>
 
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>
637
581
 
638
582
      </para>
639
583
    </informalexample>
671
615
  <refsect1 id="see_also">
672
616
    <title>SEE ALSO</title>
673
617
    <para>
674
 
      <citerefentry><refentrytitle>intro</refentrytitle>
675
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
676
618
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
677
619
      <manvolnum>8</manvolnum></citerefentry>,
678
620
      <citerefentry><refentrytitle>crypttab</refentrytitle>