/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-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
  
542
510
    </para>
543
511
  </refsect1>
544
512
  
545
 
  <refsect1 id="bugs">
546
 
    <title>BUGS</title>
547
 
    <para>
548
 
      The <option>--config-file</option> option is ignored when
549
 
      specified from within a configuration file.
550
 
    </para>
551
 
  </refsect1>
 
513
<!--   <refsect1 id="bugs"> -->
 
514
<!--     <title>BUGS</title> -->
 
515
<!--     <para> -->
 
516
<!--     </para> -->
 
517
<!--   </refsect1> -->
552
518
  
553
519
  <refsect1 id="examples">
554
520
    <title>EXAMPLE</title>
596
562
    </informalexample>
597
563
    <informalexample>
598
564
      <para>
599
 
        Read a different configuration file, run plugins from a
600
 
        different directory, specify an alternate plugin helper
601
 
        directory and add two options to the
602
 
        <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>
603
568
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
604
569
      </para>
605
570
      <para>
606
571
 
607
572
<!-- do not wrap this line -->
608
 
<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>
609
574
 
610
575
      </para>
611
576
    </informalexample>
619
584
      non-privileged.  This user and group is then what all plugins
620
585
      will be started as.  Therefore, the only way to run a plugin as
621
586
      a privileged user is to have the set-user-ID or set-group-ID bit
622
 
      set on the plugin executable file (see <citerefentry>
 
587
      set on the plugin executable files (see <citerefentry>
623
588
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
624
589
      </citerefentry>).
625
590
    </para>
643
608
  <refsect1 id="see_also">
644
609
    <title>SEE ALSO</title>
645
610
    <para>
646
 
      <citerefentry><refentrytitle>intro</refentrytitle>
647
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
648
611
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
649
612
      <manvolnum>8</manvolnum></citerefentry>,
650
613
      <citerefentry><refentrytitle>crypttab</refentrytitle>
655
618
      <manvolnum>8</manvolnum></citerefentry>,
656
619
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
657
620
      <manvolnum>8mandos</manvolnum></citerefentry>,
658
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
621
      <citerefentry><refentrytitle>password-request</refentrytitle>
659
622
      <manvolnum>8mandos</manvolnum></citerefentry>
660
623
    </para>
661
624
  </refsect1>