/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: 2008-09-04 14:04:09 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080904140409-anr3hckg8ew7q60e
* plugin-runner.xml (BUGS): Document the non-recursiveness of the
                            "--config-file" option.

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 "2015-07-20">
6
 
<!ENTITY % common SYSTEM "common.ent">
7
 
%common;
 
6
<!ENTITY TIMESTAMP "2008-09-04">
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
34
      <holder>Teddy Hogeborn</holder>
43
35
      <holder>Björn Påhlsson</holder>
44
36
    </copyright>
45
37
    <xi:include href="legalnotice.xml"/>
46
38
  </refentryinfo>
47
 
  
 
39
 
48
40
  <refmeta>
49
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
50
42
    <manvolnum>8mandos</manvolnum>
56
48
      Run Mandos plugins, pass data from first to succeed.
57
49
    </refpurpose>
58
50
  </refnamediv>
59
 
  
 
51
 
60
52
  <refsynopsisdiv>
61
53
    <cmdsynopsis>
62
54
      <command>&COMMANDNAME;</command>
63
55
      <group rep="repeat">
64
56
        <arg choice="plain"><option>--global-env=<replaceable
65
 
        >ENV</replaceable><literal>=</literal><replaceable
 
57
        >VAR</replaceable><literal>=</literal><replaceable
66
58
        >value</replaceable></option></arg>
67
59
        <arg choice="plain"><option>-G
68
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
60
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
69
61
        >value</replaceable> </option></arg>
70
62
      </group>
71
63
      <sbr/>
119
111
      <arg><option>--plugin-dir=<replaceable
120
112
      >DIRECTORY</replaceable></option></arg>
121
113
      <sbr/>
122
 
      <arg><option>--plugin-helper-dir=<replaceable
123
 
      >DIRECTORY</replaceable></option></arg>
124
 
      <sbr/>
125
114
      <arg><option>--config-file=<replaceable
126
115
      >FILE</replaceable></option></arg>
127
116
      <sbr/>
181
170
    <variablelist>
182
171
      <varlistentry>
183
172
        <term><option>--global-env
184
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
173
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
185
174
        >value</replaceable></option></term>
186
175
        <term><option>-G
187
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
176
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
188
177
        >value</replaceable></option></term>
189
178
        <listitem>
190
179
          <para>
258
247
          </para>
259
248
        </listitem>
260
249
      </varlistentry>
261
 
      
 
250
 
262
251
      <varlistentry>
263
252
        <term><option>--disable
264
253
        <replaceable>PLUGIN</replaceable></option></term>
269
258
            Disable the plugin named
270
259
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
271
260
            started.
272
 
          </para>
 
261
          </para>       
273
262
        </listitem>
274
263
      </varlistentry>
275
 
      
 
264
 
276
265
      <varlistentry>
277
266
        <term><option>--enable
278
267
        <replaceable>PLUGIN</replaceable></option></term>
287
276
          </para>
288
277
        </listitem>
289
278
      </varlistentry>
290
 
      
 
279
 
291
280
      <varlistentry>
292
281
        <term><option>--groupid
293
282
        <replaceable>ID</replaceable></option></term>
300
289
          </para>
301
290
        </listitem>
302
291
      </varlistentry>
303
 
      
 
292
 
304
293
      <varlistentry>
305
294
        <term><option>--userid
306
295
        <replaceable>ID</replaceable></option></term>
313
302
          </para>
314
303
        </listitem>
315
304
      </varlistentry>
316
 
      
 
305
 
317
306
      <varlistentry>
318
307
        <term><option>--plugin-dir
319
308
        <replaceable>DIRECTORY</replaceable></option></term>
328
317
      </varlistentry>
329
318
      
330
319
      <varlistentry>
331
 
        <term><option>--plugin-helper-dir
332
 
        <replaceable>DIRECTORY</replaceable></option></term>
333
 
        <listitem>
334
 
          <para>
335
 
            Specify a different plugin helper directory.  The default
336
 
            is <filename>/lib/mandos/plugin-helpers</filename>, which
337
 
            will exist in the initial <acronym>RAM</acronym> disk
338
 
            environment.  (This will simply be passed to all plugins
339
 
            via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
340
 
            variable.  See <xref linkend="writing_plugins"/>)
341
 
          </para>
342
 
        </listitem>
343
 
      </varlistentry>
344
 
      
345
 
      <varlistentry>
346
320
        <term><option>--config-file
347
321
        <replaceable>FILE</replaceable></option></term>
348
322
        <listitem>
391
365
          </para>
392
366
        </listitem>
393
367
      </varlistentry>
394
 
      
 
368
 
395
369
      <varlistentry>
396
370
        <term><option>--version</option></term>
397
371
        <term><option>-V</option></term>
403
377
      </varlistentry>
404
378
    </variablelist>
405
379
  </refsect1>
406
 
  
 
380
 
407
381
  <refsect1 id="overview">
408
382
    <title>OVERVIEW</title>
409
383
    <xi:include href="overview.xml"/>
429
403
      code will make this plugin-runner output the password from that
430
404
      plugin, stop any other plugins, and exit.
431
405
    </para>
432
 
    
 
406
 
433
407
    <refsect2 id="writing_plugins">
434
408
      <title>WRITING PLUGINS</title>
435
409
      <para>
442
416
        console.
443
417
      </para>
444
418
      <para>
445
 
        If the password is a single-line, manually entered passprase,
446
 
        a final trailing newline character should
447
 
        <emphasis>not</emphasis> be printed.
448
 
      </para>
449
 
      <para>
450
419
        The plugin will run in the initial RAM disk environment, so
451
420
        care must be taken not to depend on any files or running
452
 
        services not available there.  Any helper executables required
453
 
        by the plugin (which are not in the <envar>PATH</envar>) can
454
 
        be placed in the plugin helper directory, the name of which
455
 
        will be made available to the plugin via the
456
 
        <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
 
421
        services not available there.
457
422
      </para>
458
423
      <para>
459
424
        The plugin must exit cleanly and free all allocated resources
502
467
      only passes on its environment to all the plugins.  The
503
468
      environment passed to plugins can be modified using the
504
469
      <option>--global-env</option> and <option>--env-for</option>
505
 
      options.  Also, the <option>--plugin-helper-dir</option> option
506
 
      will affect the environment variable
507
 
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
 
470
      options.
508
471
    </para>
509
472
  </refsect1>
510
473
  
601
564
    </informalexample>
602
565
    <informalexample>
603
566
      <para>
604
 
        Read a different configuration file, run plugins from a
605
 
        different directory, specify an alternate plugin helper
606
 
        directory and add two options to the
607
 
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
 
567
        Run plugins from a different directory and add two
 
568
        options to the <citerefentry><refentrytitle
 
569
        >password-request</refentrytitle>
608
570
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
609
571
      </para>
610
572
      <para>
611
573
 
612
574
<!-- do not wrap this line -->
613
 
<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>
 
575
<userinput>&COMMANDNAME;  --plugin-dir=plugins.d --options-for=password-request:--pubkey=keydir/pubkey.txt,--seckey=keydir/seckey.txt</userinput>
614
576
 
615
577
      </para>
616
578
    </informalexample>
624
586
      non-privileged.  This user and group is then what all plugins
625
587
      will be started as.  Therefore, the only way to run a plugin as
626
588
      a privileged user is to have the set-user-ID or set-group-ID bit
627
 
      set on the plugin executable file (see <citerefentry>
 
589
      set on the plugin executable files (see <citerefentry>
628
590
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
629
591
      </citerefentry>).
630
592
    </para>
648
610
  <refsect1 id="see_also">
649
611
    <title>SEE ALSO</title>
650
612
    <para>
651
 
      <citerefentry><refentrytitle>intro</refentrytitle>
652
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
653
613
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
654
614
      <manvolnum>8</manvolnum></citerefentry>,
655
615
      <citerefentry><refentrytitle>crypttab</refentrytitle>
660
620
      <manvolnum>8</manvolnum></citerefentry>,
661
621
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
662
622
      <manvolnum>8mandos</manvolnum></citerefentry>,
663
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
623
      <citerefentry><refentrytitle>password-request</refentrytitle>
664
624
      <manvolnum>8mandos</manvolnum></citerefentry>
665
625
    </para>
666
626
  </refsect1>