/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: 2024-09-12 16:21:53 UTC
  • mfrom: (1301 trunk)
  • mto: This revision was merged to the branch mainline in revision 1302.
  • Revision ID: teddy@recompile.se-20240912162153-grzvz1n3u1iruu93
Merge from trunk

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugin-runner.xml
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
4
<!ENTITY COMMANDNAME "plugin-runner">
5
 
<!ENTITY TIMESTAMP "2009-01-17">
 
5
<!ENTITY TIMESTAMP "2023-04-30">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
19
19
        <firstname>Björn</firstname>
20
20
        <surname>Påhlsson</surname>
21
21
        <address>
22
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
23
23
        </address>
24
24
      </author>
25
25
      <author>
26
26
        <firstname>Teddy</firstname>
27
27
        <surname>Hogeborn</surname>
28
28
        <address>
29
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
30
30
        </address>
31
31
      </author>
32
32
    </authorgroup>
33
33
    <copyright>
34
34
      <year>2008</year>
35
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
      <year>2018</year>
 
45
      <year>2019</year>
36
46
      <holder>Teddy Hogeborn</holder>
37
47
      <holder>Björn Påhlsson</holder>
38
48
    </copyright>
113
123
      <arg><option>--plugin-dir=<replaceable
114
124
      >DIRECTORY</replaceable></option></arg>
115
125
      <sbr/>
 
126
      <arg><option>--plugin-helper-dir=<replaceable
 
127
      >DIRECTORY</replaceable></option></arg>
 
128
      <sbr/>
116
129
      <arg><option>--config-file=<replaceable
117
130
      >FILE</replaceable></option></arg>
118
131
      <sbr/>
260
273
            Disable the plugin named
261
274
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
262
275
            started.
263
 
          </para>       
 
276
          </para>
264
277
        </listitem>
265
278
      </varlistentry>
266
279
      
319
332
      </varlistentry>
320
333
      
321
334
      <varlistentry>
 
335
        <term><option>--plugin-helper-dir
 
336
        <replaceable>DIRECTORY</replaceable></option></term>
 
337
        <listitem>
 
338
          <para>
 
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"/>)
 
345
          </para>
 
346
        </listitem>
 
347
      </varlistentry>
 
348
      
 
349
      <varlistentry>
322
350
        <term><option>--config-file
323
351
        <replaceable>FILE</replaceable></option></term>
324
352
        <listitem>
395
423
    <title>PLUGINS</title>
396
424
    <para>
397
425
      This program will get a password by running a number of
398
 
      <firstterm>plugins</firstterm>, which are simply executable
399
 
      programs in a directory in the initial <acronym>RAM</acronym>
400
 
      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
401
429
      <filename>/lib/mandos/plugins.d</filename>, but this can be
402
430
      changed with the <option>--plugin-dir</option> option.  The
403
431
      plugins are started in parallel, and the first plugin to output
409
437
    <refsect2 id="writing_plugins">
410
438
      <title>WRITING PLUGINS</title>
411
439
      <para>
412
 
        A plugin is simply a program which prints a password to its
413
 
        standard output and then exits with a successful (zero) exit
414
 
        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
415
443
        standard output will be ignored by the plugin runner.  Any
416
444
        output on its standard error channel will simply be passed to
417
445
        the standard error of the plugin runner, usually the system
425
453
      <para>
426
454
        The plugin will run in the initial RAM disk environment, so
427
455
        care must be taken not to depend on any files or running
428
 
        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.
429
461
      </para>
430
462
      <para>
431
463
        The plugin must exit cleanly and free all allocated resources
474
506
      only passes on its environment to all the plugins.  The
475
507
      environment passed to plugins can be modified using the
476
508
      <option>--global-env</option> and <option>--env-for</option>
477
 
      options.
 
509
      options.  Also, the <option>--plugin-helper-dir</option> option
 
510
      will affect the environment variable
 
511
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
478
512
    </para>
479
513
  </refsect1>
480
514
  
513
547
            </para>
514
548
          </listitem>
515
549
        </varlistentry>
 
550
        <varlistentry>
 
551
          <term><filename class="directory"
 
552
          >/lib/mandos/plugins.d</filename></term>
 
553
          <listitem>
 
554
            <para>
 
555
              The default plugin directory; can be changed by the
 
556
              <option>--plugin-dir</option> option.
 
557
            </para>
 
558
          </listitem>
 
559
        </varlistentry>
 
560
        <varlistentry>
 
561
          <term><filename class="directory"
 
562
          >/lib/mandos/plugin-helpers</filename></term>
 
563
          <listitem>
 
564
            <para>
 
565
              The default plugin helper directory; can be changed by
 
566
              the <option>--plugin-helper-dir</option> option.
 
567
            </para>
 
568
          </listitem>
 
569
        </varlistentry>
516
570
      </variablelist>
517
571
    </para>
518
572
  </refsect1>
523
577
      The <option>--config-file</option> option is ignored when
524
578
      specified from within a configuration file.
525
579
    </para>
 
580
    <xi:include href="bugs.xml"/>
526
581
  </refsect1>
527
582
  
528
583
  <refsect1 id="examples">
571
626
    </informalexample>
572
627
    <informalexample>
573
628
      <para>
574
 
        Run plugins from a different directory, read a different
575
 
        configuration file, and add two options to the
 
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
576
632
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
577
633
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
578
634
      </para>
579
635
      <para>
580
636
 
581
637
<!-- do not wrap this line -->
582
 
<userinput>cd /etc/keys/mandos; &COMMANDNAME;  --config-file=/etc/mandos/plugin-runner.conf --plugin-dir /usr/lib/mandos/plugins.d --options-for=mandos-client:--pubkey=pubkey.txt,--seckey=seckey.txt</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,&#x200b;--seckey=seckey.txt,&#x200b;--tls-pubkey=tls-pubkey.pem,&#x200b;--tls-privkey=tls-privkey.pem</userinput>
583
639
 
584
640
      </para>
585
641
    </informalexample>
617
673
  <refsect1 id="see_also">
618
674
    <title>SEE ALSO</title>
619
675
    <para>
 
676
      <citerefentry><refentrytitle>intro</refentrytitle>
 
677
      <manvolnum>8mandos</manvolnum></citerefentry>,
620
678
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
621
679
      <manvolnum>8</manvolnum></citerefentry>,
622
680
      <citerefentry><refentrytitle>crypttab</refentrytitle>