/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 13:36:59 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080904133659-0omre4j6luosb20q
* mandos-clients.conf.xml (OPTIONS): Improved spelling.

* mandos.conf.xml (BUGS): - '' -

* mandos.xml (BUGS): - '' -

* plugin-runner.xml (NAME): Fix spelling by changing wording.
  (OPTIONS): Improved spelling.
  (EXAMPLE): Do not use obsolete "--keydir" option.  Improved wording.

* plugins.d/password-prompt.xml (DESCRIPTION): Improved spelling.
  (EXAMPLE): Add <acronym> tag.
  (SECURITY): Improved spelling.

* plugins.d/password-request.xml (SYNOPSIS): Changed replaceable to
                                             match OPTIONS section.
  (DESCRIPTION, OVERVIEW): Improved spelling.

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
  
547
510
    </para>
548
511
  </refsect1>
549
512
  
550
 
  <refsect1 id="bugs">
551
 
    <title>BUGS</title>
552
 
    <para>
553
 
      The <option>--config-file</option> option is ignored when
554
 
      specified from within a configuration file.
555
 
    </para>
556
 
  </refsect1>
 
513
<!--   <refsect1 id="bugs"> -->
 
514
<!--     <title>BUGS</title> -->
 
515
<!--     <para> -->
 
516
<!--     </para> -->
 
517
<!--   </refsect1> -->
557
518
  
558
519
  <refsect1 id="examples">
559
520
    <title>EXAMPLE</title>
601
562
    </informalexample>
602
563
    <informalexample>
603
564
      <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>
 
565
        Run plugins from a different directory and add two
 
566
        options to the <citerefentry><refentrytitle
 
567
        >password-request</refentrytitle>
608
568
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
609
569
      </para>
610
570
      <para>
611
571
 
612
572
<!-- 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>
 
573
<userinput>&COMMANDNAME;  --plugin-dir=plugins.d --options-for=password-request:--pubkey=keydir/pubkey.txt,--seckey=keydir/seckey.txt</userinput>
614
574
 
615
575
      </para>
616
576
    </informalexample>
624
584
      non-privileged.  This user and group is then what all plugins
625
585
      will be started as.  Therefore, the only way to run a plugin as
626
586
      a privileged user is to have the set-user-ID or set-group-ID bit
627
 
      set on the plugin executable file (see <citerefentry>
 
587
      set on the plugin executable files (see <citerefentry>
628
588
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
629
589
      </citerefentry>).
630
590
    </para>
648
608
  <refsect1 id="see_also">
649
609
    <title>SEE ALSO</title>
650
610
    <para>
651
 
      <citerefentry><refentrytitle>intro</refentrytitle>
652
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
653
611
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
654
612
      <manvolnum>8</manvolnum></citerefentry>,
655
613
      <citerefentry><refentrytitle>crypttab</refentrytitle>
660
618
      <manvolnum>8</manvolnum></citerefentry>,
661
619
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
662
620
      <manvolnum>8mandos</manvolnum></citerefentry>,
663
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
621
      <citerefentry><refentrytitle>password-request</refentrytitle>
664
622
      <manvolnum>8mandos</manvolnum></citerefentry>
665
623
    </para>
666
624
  </refsect1>