/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: 2025-06-27 19:49:05 UTC
  • Revision ID: teddy@recompile.se-20250627194905-ijufqn8ytzdgkf34
Update copyright year

* dracut-module/ask-password-mandos.service: Update copyright year to
  2024.
* dracut-module/password-agent.c: Update copyright year to 2023.
* initramfs-unpack: Update copyright year to 2024.
* mandos: - '' -
* mandos-clients.conf.xml: Update copyright year to 2023.
* mandos-ctl: Update copyright year to 2024.
* mandos-keygen: - '' -
* mandos-monitor: - '' -
* mandos.conf.xml: - '' -
* mandos.xml: Update copyright year to 2022.
* plugin-runner.xml: Update copyright year to 2024.
* plugins.d/mandos-client.xml: - '' -
* plugins.d/plymouth.c: - '' -

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 "2025-06-27">
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>
 
46
      <year>2020</year>
 
47
      <year>2021</year>
 
48
      <year>2022</year>
 
49
      <year>2023</year>
 
50
      <year>2024</year>
36
51
      <holder>Teddy Hogeborn</holder>
37
52
      <holder>Björn Påhlsson</holder>
38
53
    </copyright>
113
128
      <arg><option>--plugin-dir=<replaceable
114
129
      >DIRECTORY</replaceable></option></arg>
115
130
      <sbr/>
 
131
      <arg><option>--plugin-helper-dir=<replaceable
 
132
      >DIRECTORY</replaceable></option></arg>
 
133
      <sbr/>
116
134
      <arg><option>--config-file=<replaceable
117
135
      >FILE</replaceable></option></arg>
118
136
      <sbr/>
260
278
            Disable the plugin named
261
279
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
262
280
            started.
263
 
          </para>       
 
281
          </para>
264
282
        </listitem>
265
283
      </varlistentry>
266
284
      
319
337
      </varlistentry>
320
338
      
321
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>
322
355
        <term><option>--config-file
323
356
        <replaceable>FILE</replaceable></option></term>
324
357
        <listitem>
395
428
    <title>PLUGINS</title>
396
429
    <para>
397
430
      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
 
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
401
434
      <filename>/lib/mandos/plugins.d</filename>, but this can be
402
435
      changed with the <option>--plugin-dir</option> option.  The
403
436
      plugins are started in parallel, and the first plugin to output
409
442
    <refsect2 id="writing_plugins">
410
443
      <title>WRITING PLUGINS</title>
411
444
      <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
 
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
415
448
        standard output will be ignored by the plugin runner.  Any
416
449
        output on its standard error channel will simply be passed to
417
450
        the standard error of the plugin runner, usually the system
425
458
      <para>
426
459
        The plugin will run in the initial RAM disk environment, so
427
460
        care must be taken not to depend on any files or running
428
 
        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.
429
466
      </para>
430
467
      <para>
431
468
        The plugin must exit cleanly and free all allocated resources
474
511
      only passes on its environment to all the plugins.  The
475
512
      environment passed to plugins can be modified using the
476
513
      <option>--global-env</option> and <option>--env-for</option>
477
 
      options.
 
514
      options.  Also, the <option>--plugin-helper-dir</option> option
 
515
      will affect the environment variable
 
516
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
478
517
    </para>
479
518
  </refsect1>
480
519
  
513
552
            </para>
514
553
          </listitem>
515
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>
516
575
      </variablelist>
517
576
    </para>
518
577
  </refsect1>
523
582
      The <option>--config-file</option> option is ignored when
524
583
      specified from within a configuration file.
525
584
    </para>
 
585
    <xi:include href="bugs.xml"/>
526
586
  </refsect1>
527
587
  
528
588
  <refsect1 id="examples">
571
631
    </informalexample>
572
632
    <informalexample>
573
633
      <para>
574
 
        Run plugins from a different directory, read a different
575
 
        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
576
637
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
577
638
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
578
639
      </para>
579
640
      <para>
580
641
 
581
642
<!-- 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>
 
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>
583
644
 
584
645
      </para>
585
646
    </informalexample>
617
678
  <refsect1 id="see_also">
618
679
    <title>SEE ALSO</title>
619
680
    <para>
 
681
      <citerefentry><refentrytitle>intro</refentrytitle>
 
682
      <manvolnum>8mandos</manvolnum></citerefentry>,
620
683
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
621
684
      <manvolnum>8</manvolnum></citerefentry>,
622
685
      <citerefentry><refentrytitle>crypttab</refentrytitle>