/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

  • Committer: Björn Påhlsson
  • Date: 2010-09-07 16:48:58 UTC
  • mto: (237.7.1 mandos)
  • mto: This revision was merged to the branch mainline in revision 270.
  • Revision ID: belorn@fukt.bsnet.se-20100907164858-tcg8hkxdj41zizac
mandos server: Added debuglevel that adjust at what level information
               should be reported.
plugin-runner, askpass-fifo, password-prompt, splasy, usplash:
               Using error instead of perror

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 "2025-06-27">
 
5
<!ENTITY TIMESTAMP "2009-01-17">
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@recompile.se</email>
 
22
          <email>belorn@fukt.bsnet.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@recompile.se</email>
 
29
          <email>teddy@fukt.bsnet.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>
46
 
      <year>2020</year>
47
 
      <year>2021</year>
48
 
      <year>2022</year>
49
 
      <year>2023</year>
50
 
      <year>2024</year>
51
36
      <holder>Teddy Hogeborn</holder>
52
37
      <holder>Björn Påhlsson</holder>
53
38
    </copyright>
128
113
      <arg><option>--plugin-dir=<replaceable
129
114
      >DIRECTORY</replaceable></option></arg>
130
115
      <sbr/>
131
 
      <arg><option>--plugin-helper-dir=<replaceable
132
 
      >DIRECTORY</replaceable></option></arg>
133
 
      <sbr/>
134
116
      <arg><option>--config-file=<replaceable
135
117
      >FILE</replaceable></option></arg>
136
118
      <sbr/>
278
260
            Disable the plugin named
279
261
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
280
262
            started.
281
 
          </para>
 
263
          </para>       
282
264
        </listitem>
283
265
      </varlistentry>
284
266
      
337
319
      </varlistentry>
338
320
      
339
321
      <varlistentry>
340
 
        <term><option>--plugin-helper-dir
341
 
        <replaceable>DIRECTORY</replaceable></option></term>
342
 
        <listitem>
343
 
          <para>
344
 
            Specify a different plugin helper directory.  The default
345
 
            is <filename>/lib/mandos/plugin-helpers</filename>, which
346
 
            will exist in the initial <acronym>RAM</acronym> disk
347
 
            environment.  (This will simply be passed to all plugins
348
 
            via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
349
 
            variable.  See <xref linkend="writing_plugins"/>)
350
 
          </para>
351
 
        </listitem>
352
 
      </varlistentry>
353
 
      
354
 
      <varlistentry>
355
322
        <term><option>--config-file
356
323
        <replaceable>FILE</replaceable></option></term>
357
324
        <listitem>
428
395
    <title>PLUGINS</title>
429
396
    <para>
430
397
      This program will get a password by running a number of
431
 
      <firstterm>plugins</firstterm>, which are executable programs in
432
 
      a directory in the initial <acronym>RAM</acronym> disk
433
 
      environment.  The default directory is
 
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
434
401
      <filename>/lib/mandos/plugins.d</filename>, but this can be
435
402
      changed with the <option>--plugin-dir</option> option.  The
436
403
      plugins are started in parallel, and the first plugin to output
442
409
    <refsect2 id="writing_plugins">
443
410
      <title>WRITING PLUGINS</title>
444
411
      <para>
445
 
        A plugin is an executable program which prints a password to
446
 
        its standard output and then exits with a successful (zero)
447
 
        exit status.  If the exit status is not zero, any output on
 
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
448
415
        standard output will be ignored by the plugin runner.  Any
449
416
        output on its standard error channel will simply be passed to
450
417
        the standard error of the plugin runner, usually the system
458
425
      <para>
459
426
        The plugin will run in the initial RAM disk environment, so
460
427
        care must be taken not to depend on any files or running
461
 
        services not available there.  Any helper executables required
462
 
        by the plugin (which are not in the <envar>PATH</envar>) can
463
 
        be placed in the plugin helper directory, the name of which
464
 
        will be made available to the plugin via the
465
 
        <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
 
428
        services not available there.
466
429
      </para>
467
430
      <para>
468
431
        The plugin must exit cleanly and free all allocated resources
511
474
      only passes on its environment to all the plugins.  The
512
475
      environment passed to plugins can be modified using the
513
476
      <option>--global-env</option> and <option>--env-for</option>
514
 
      options.  Also, the <option>--plugin-helper-dir</option> option
515
 
      will affect the environment variable
516
 
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
 
477
      options.
517
478
    </para>
518
479
  </refsect1>
519
480
  
552
513
            </para>
553
514
          </listitem>
554
515
        </varlistentry>
555
 
        <varlistentry>
556
 
          <term><filename class="directory"
557
 
          >/lib/mandos/plugins.d</filename></term>
558
 
          <listitem>
559
 
            <para>
560
 
              The default plugin directory; can be changed by the
561
 
              <option>--plugin-dir</option> option.
562
 
            </para>
563
 
          </listitem>
564
 
        </varlistentry>
565
 
        <varlistentry>
566
 
          <term><filename class="directory"
567
 
          >/lib/mandos/plugin-helpers</filename></term>
568
 
          <listitem>
569
 
            <para>
570
 
              The default plugin helper directory; can be changed by
571
 
              the <option>--plugin-helper-dir</option> option.
572
 
            </para>
573
 
          </listitem>
574
 
        </varlistentry>
575
516
      </variablelist>
576
517
    </para>
577
518
  </refsect1>
582
523
      The <option>--config-file</option> option is ignored when
583
524
      specified from within a configuration file.
584
525
    </para>
585
 
    <xi:include href="bugs.xml"/>
586
526
  </refsect1>
587
527
  
588
528
  <refsect1 id="examples">
631
571
    </informalexample>
632
572
    <informalexample>
633
573
      <para>
634
 
        Read a different configuration file, run plugins from a
635
 
        different directory, specify an alternate plugin helper
636
 
        directory and add four options to the
 
574
        Run plugins from a different directory, read a different
 
575
        configuration file, and add two options to the
637
576
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
638
577
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
639
578
      </para>
640
579
      <para>
641
580
 
642
581
<!-- do not wrap this line -->
643
 
<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>
 
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>
644
583
 
645
584
      </para>
646
585
    </informalexample>
678
617
  <refsect1 id="see_also">
679
618
    <title>SEE ALSO</title>
680
619
    <para>
681
 
      <citerefentry><refentrytitle>intro</refentrytitle>
682
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
683
620
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
684
621
      <manvolnum>8</manvolnum></citerefentry>,
685
622
      <citerefentry><refentrytitle>crypttab</refentrytitle>