/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: Teddy Hogeborn
  • Date: 2025-06-27 20:06:35 UTC
  • Revision ID: teddy@recompile.se-20250627200635-v0jcpgcw3ar0o3rd
Tags: version-1.8.19-1
http://bugs.debian.org/1107761
Version 1.8.19-1

* Makefile (version): Change to "1.8.19".
* NEWS (Version 1.8.19): Add new entry.
* debian/changelog (1.8.19-1): - '' -

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 "2011-10-05">
 
5
<!ENTITY TIMESTAMP "2025-06-27">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
33
33
    <copyright>
34
34
      <year>2008</year>
35
35
      <year>2009</year>
 
36
      <year>2010</year>
36
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>
37
51
      <holder>Teddy Hogeborn</holder>
38
52
      <holder>Björn Påhlsson</holder>
39
53
    </copyright>
114
128
      <arg><option>--plugin-dir=<replaceable
115
129
      >DIRECTORY</replaceable></option></arg>
116
130
      <sbr/>
 
131
      <arg><option>--plugin-helper-dir=<replaceable
 
132
      >DIRECTORY</replaceable></option></arg>
 
133
      <sbr/>
117
134
      <arg><option>--config-file=<replaceable
118
135
      >FILE</replaceable></option></arg>
119
136
      <sbr/>
320
337
      </varlistentry>
321
338
      
322
339
      <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>
323
355
        <term><option>--config-file
324
356
        <replaceable>FILE</replaceable></option></term>
325
357
        <listitem>
396
428
    <title>PLUGINS</title>
397
429
    <para>
398
430
      This program will get a password by running a number of
399
 
      <firstterm>plugins</firstterm>, which are simply executable
400
 
      programs in a directory in the initial <acronym>RAM</acronym>
401
 
      disk environment.  The default directory is
 
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
402
434
      <filename>/lib/mandos/plugins.d</filename>, but this can be
403
435
      changed with the <option>--plugin-dir</option> option.  The
404
436
      plugins are started in parallel, and the first plugin to output
410
442
    <refsect2 id="writing_plugins">
411
443
      <title>WRITING PLUGINS</title>
412
444
      <para>
413
 
        A plugin is simply a program which prints a password to its
414
 
        standard output and then exits with a successful (zero) exit
415
 
        status.  If the exit status is not zero, any output on
 
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
416
448
        standard output will be ignored by the plugin runner.  Any
417
449
        output on its standard error channel will simply be passed to
418
450
        the standard error of the plugin runner, usually the system
426
458
      <para>
427
459
        The plugin will run in the initial RAM disk environment, so
428
460
        care must be taken not to depend on any files or running
429
 
        services not available there.
 
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.
430
466
      </para>
431
467
      <para>
432
468
        The plugin must exit cleanly and free all allocated resources
475
511
      only passes on its environment to all the plugins.  The
476
512
      environment passed to plugins can be modified using the
477
513
      <option>--global-env</option> and <option>--env-for</option>
478
 
      options.
 
514
      options.  Also, the <option>--plugin-helper-dir</option> option
 
515
      will affect the environment variable
 
516
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
479
517
    </para>
480
518
  </refsect1>
481
519
  
514
552
            </para>
515
553
          </listitem>
516
554
        </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>
517
575
      </variablelist>
518
576
    </para>
519
577
  </refsect1>
524
582
      The <option>--config-file</option> option is ignored when
525
583
      specified from within a configuration file.
526
584
    </para>
 
585
    <xi:include href="bugs.xml"/>
527
586
  </refsect1>
528
587
  
529
588
  <refsect1 id="examples">
572
631
    </informalexample>
573
632
    <informalexample>
574
633
      <para>
575
 
        Run plugins from a different directory, read a different
576
 
        configuration file, and add two options to the
 
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
577
637
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
578
638
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
579
639
      </para>
580
640
      <para>
581
641
 
582
642
<!-- do not wrap this line -->
583
 
<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>
 
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>
584
644
 
585
645
      </para>
586
646
    </informalexample>