/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: 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-06-28">
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>2012</year>
37
34
      <holder>Teddy Hogeborn</holder>
38
35
      <holder>Björn Påhlsson</holder>
39
36
    </copyright>
40
37
    <xi:include href="legalnotice.xml"/>
41
38
  </refentryinfo>
42
 
  
 
39
 
43
40
  <refmeta>
44
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
45
42
    <manvolnum>8mandos</manvolnum>
51
48
      Run Mandos plugins, pass data from first to succeed.
52
49
    </refpurpose>
53
50
  </refnamediv>
54
 
  
 
51
 
55
52
  <refsynopsisdiv>
56
53
    <cmdsynopsis>
57
54
      <command>&COMMANDNAME;</command>
58
55
      <group rep="repeat">
59
56
        <arg choice="plain"><option>--global-env=<replaceable
60
 
        >ENV</replaceable><literal>=</literal><replaceable
 
57
        >VAR</replaceable><literal>=</literal><replaceable
61
58
        >value</replaceable></option></arg>
62
59
        <arg choice="plain"><option>-G
63
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
60
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
64
61
        >value</replaceable> </option></arg>
65
62
      </group>
66
63
      <sbr/>
114
111
      <arg><option>--plugin-dir=<replaceable
115
112
      >DIRECTORY</replaceable></option></arg>
116
113
      <sbr/>
117
 
      <arg><option>--plugin-helper-dir=<replaceable
118
 
      >DIRECTORY</replaceable></option></arg>
119
 
      <sbr/>
120
114
      <arg><option>--config-file=<replaceable
121
115
      >FILE</replaceable></option></arg>
122
116
      <sbr/>
176
170
    <variablelist>
177
171
      <varlistentry>
178
172
        <term><option>--global-env
179
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
173
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
180
174
        >value</replaceable></option></term>
181
175
        <term><option>-G
182
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
176
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
183
177
        >value</replaceable></option></term>
184
178
        <listitem>
185
179
          <para>
253
247
          </para>
254
248
        </listitem>
255
249
      </varlistentry>
256
 
      
 
250
 
257
251
      <varlistentry>
258
252
        <term><option>--disable
259
253
        <replaceable>PLUGIN</replaceable></option></term>
264
258
            Disable the plugin named
265
259
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
266
260
            started.
267
 
          </para>
 
261
          </para>       
268
262
        </listitem>
269
263
      </varlistentry>
270
 
      
 
264
 
271
265
      <varlistentry>
272
266
        <term><option>--enable
273
267
        <replaceable>PLUGIN</replaceable></option></term>
282
276
          </para>
283
277
        </listitem>
284
278
      </varlistentry>
285
 
      
 
279
 
286
280
      <varlistentry>
287
281
        <term><option>--groupid
288
282
        <replaceable>ID</replaceable></option></term>
295
289
          </para>
296
290
        </listitem>
297
291
      </varlistentry>
298
 
      
 
292
 
299
293
      <varlistentry>
300
294
        <term><option>--userid
301
295
        <replaceable>ID</replaceable></option></term>
308
302
          </para>
309
303
        </listitem>
310
304
      </varlistentry>
311
 
      
 
305
 
312
306
      <varlistentry>
313
307
        <term><option>--plugin-dir
314
308
        <replaceable>DIRECTORY</replaceable></option></term>
323
317
      </varlistentry>
324
318
      
325
319
      <varlistentry>
326
 
        <term><option>--plugin-helper-dir
327
 
        <replaceable>DIRECTORY</replaceable></option></term>
328
 
        <listitem>
329
 
          <para>
330
 
            Specify a different plugin helper directory.  The default
331
 
            is <filename>/lib/mandos/plugin-helpers</filename>, which
332
 
            will exist in the initial <acronym>RAM</acronym> disk
333
 
            environment.  (This will simply be passed to all plugins
334
 
            via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
335
 
            variable.  See <xref linkend="writing_plugins"/>)
336
 
          </para>
337
 
        </listitem>
338
 
      </varlistentry>
339
 
      
340
 
      <varlistentry>
341
320
        <term><option>--config-file
342
321
        <replaceable>FILE</replaceable></option></term>
343
322
        <listitem>
386
365
          </para>
387
366
        </listitem>
388
367
      </varlistentry>
389
 
      
 
368
 
390
369
      <varlistentry>
391
370
        <term><option>--version</option></term>
392
371
        <term><option>-V</option></term>
398
377
      </varlistentry>
399
378
    </variablelist>
400
379
  </refsect1>
401
 
  
 
380
 
402
381
  <refsect1 id="overview">
403
382
    <title>OVERVIEW</title>
404
383
    <xi:include href="overview.xml"/>
424
403
      code will make this plugin-runner output the password from that
425
404
      plugin, stop any other plugins, and exit.
426
405
    </para>
427
 
    
 
406
 
428
407
    <refsect2 id="writing_plugins">
429
408
      <title>WRITING PLUGINS</title>
430
409
      <para>
437
416
        console.
438
417
      </para>
439
418
      <para>
440
 
        If the password is a single-line, manually entered passprase,
441
 
        a final trailing newline character should
442
 
        <emphasis>not</emphasis> be printed.
443
 
      </para>
444
 
      <para>
445
419
        The plugin will run in the initial RAM disk environment, so
446
420
        care must be taken not to depend on any files or running
447
 
        services not available there.  Any helper executables required
448
 
        by the plugin (which are not in the <envar>PATH</envar>) can
449
 
        be placed in the plugin helper directory, the name of which
450
 
        will be made available to the plugin via the
451
 
        <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
 
421
        services not available there.
452
422
      </para>
453
423
      <para>
454
424
        The plugin must exit cleanly and free all allocated resources
497
467
      only passes on its environment to all the plugins.  The
498
468
      environment passed to plugins can be modified using the
499
469
      <option>--global-env</option> and <option>--env-for</option>
500
 
      options.  Also, the <option>--plugin-helper-dir</option> option
501
 
      will affect the environment variable
502
 
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
 
470
      options.
503
471
    </para>
504
472
  </refsect1>
505
473
  
596
564
    </informalexample>
597
565
    <informalexample>
598
566
      <para>
599
 
        Run plugins from a different directory, read a different
600
 
        configuration file, and add two options to the
601
 
        <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>
602
570
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
603
571
      </para>
604
572
      <para>
605
573
 
606
574
<!-- do not wrap this line -->
607
 
<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>
 
575
<userinput>&COMMANDNAME;  --plugin-dir=plugins.d --options-for=password-request:--pubkey=keydir/pubkey.txt,--seckey=keydir/seckey.txt</userinput>
608
576
 
609
577
      </para>
610
578
    </informalexample>
618
586
      non-privileged.  This user and group is then what all plugins
619
587
      will be started as.  Therefore, the only way to run a plugin as
620
588
      a privileged user is to have the set-user-ID or set-group-ID bit
621
 
      set on the plugin executable file (see <citerefentry>
 
589
      set on the plugin executable files (see <citerefentry>
622
590
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
623
591
      </citerefentry>).
624
592
    </para>
642
610
  <refsect1 id="see_also">
643
611
    <title>SEE ALSO</title>
644
612
    <para>
645
 
      <citerefentry><refentrytitle>intro</refentrytitle>
646
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
647
613
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
648
614
      <manvolnum>8</manvolnum></citerefentry>,
649
615
      <citerefentry><refentrytitle>crypttab</refentrytitle>
654
620
      <manvolnum>8</manvolnum></citerefentry>,
655
621
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
656
622
      <manvolnum>8mandos</manvolnum></citerefentry>,
657
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
623
      <citerefentry><refentrytitle>password-request</refentrytitle>
658
624
      <manvolnum>8mandos</manvolnum></citerefentry>
659
625
    </para>
660
626
  </refsect1>