/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-05 07:11:24 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080905071124-9dq11jq5rfd6zfxf
* Makefile: Changed to use symbolic instead of octal modes throughout.
  (KEYDIR): New variable for the key directory.
  (install-server): Bug fix: remove "--parents" from install args.
  (install-client): Bug fix: - '' -  Also create key directory.  Do
                    not chmod plugin dir.  Create custom plugin directory
                    if not the same as normal plugin directory.  Add
                    "--dir" option to "mandos-keygen".  Add note about
                    running "mandos-keygen --password".
  (uninstall-server): Do not depend on the installed server binary,
                      since this made it impossible to do a purge
                      after an uninstall.
  (purge-client): Shred seckey.txt.  Use $(KEYDIR).

* README: Improved wording.

* initramfs-tools-hook: Use a loop to find prefix.  Also find keydir.
                        Remove "${DESTDIR}" from "copy_exec".  Do not
                        try to copy literal "*" if no custom plugins
                        are found.  Copy key files from keydir, not
                        config dir.  Only repair mode on directories
                        that actually exist.  Do not run chmod if
                        nothing needs repairing.

* plugin-runner.conf: New file.

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 "2017-02-23">
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
 
      <year>2016</year>
43
 
      <year>2017</year>
44
34
      <holder>Teddy Hogeborn</holder>
45
35
      <holder>Björn Påhlsson</holder>
46
36
    </copyright>
47
37
    <xi:include href="legalnotice.xml"/>
48
38
  </refentryinfo>
49
 
  
 
39
 
50
40
  <refmeta>
51
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
52
42
    <manvolnum>8mandos</manvolnum>
58
48
      Run Mandos plugins, pass data from first to succeed.
59
49
    </refpurpose>
60
50
  </refnamediv>
61
 
  
 
51
 
62
52
  <refsynopsisdiv>
63
53
    <cmdsynopsis>
64
54
      <command>&COMMANDNAME;</command>
65
55
      <group rep="repeat">
66
56
        <arg choice="plain"><option>--global-env=<replaceable
67
 
        >ENV</replaceable><literal>=</literal><replaceable
 
57
        >VAR</replaceable><literal>=</literal><replaceable
68
58
        >value</replaceable></option></arg>
69
59
        <arg choice="plain"><option>-G
70
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
60
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
71
61
        >value</replaceable> </option></arg>
72
62
      </group>
73
63
      <sbr/>
121
111
      <arg><option>--plugin-dir=<replaceable
122
112
      >DIRECTORY</replaceable></option></arg>
123
113
      <sbr/>
124
 
      <arg><option>--plugin-helper-dir=<replaceable
125
 
      >DIRECTORY</replaceable></option></arg>
126
 
      <sbr/>
127
114
      <arg><option>--config-file=<replaceable
128
115
      >FILE</replaceable></option></arg>
129
116
      <sbr/>
183
170
    <variablelist>
184
171
      <varlistentry>
185
172
        <term><option>--global-env
186
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
173
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
187
174
        >value</replaceable></option></term>
188
175
        <term><option>-G
189
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
176
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
190
177
        >value</replaceable></option></term>
191
178
        <listitem>
192
179
          <para>
260
247
          </para>
261
248
        </listitem>
262
249
      </varlistentry>
263
 
      
 
250
 
264
251
      <varlistentry>
265
252
        <term><option>--disable
266
253
        <replaceable>PLUGIN</replaceable></option></term>
271
258
            Disable the plugin named
272
259
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
273
260
            started.
274
 
          </para>
 
261
          </para>       
275
262
        </listitem>
276
263
      </varlistentry>
277
 
      
 
264
 
278
265
      <varlistentry>
279
266
        <term><option>--enable
280
267
        <replaceable>PLUGIN</replaceable></option></term>
289
276
          </para>
290
277
        </listitem>
291
278
      </varlistentry>
292
 
      
 
279
 
293
280
      <varlistentry>
294
281
        <term><option>--groupid
295
282
        <replaceable>ID</replaceable></option></term>
302
289
          </para>
303
290
        </listitem>
304
291
      </varlistentry>
305
 
      
 
292
 
306
293
      <varlistentry>
307
294
        <term><option>--userid
308
295
        <replaceable>ID</replaceable></option></term>
315
302
          </para>
316
303
        </listitem>
317
304
      </varlistentry>
318
 
      
 
305
 
319
306
      <varlistentry>
320
307
        <term><option>--plugin-dir
321
308
        <replaceable>DIRECTORY</replaceable></option></term>
330
317
      </varlistentry>
331
318
      
332
319
      <varlistentry>
333
 
        <term><option>--plugin-helper-dir
334
 
        <replaceable>DIRECTORY</replaceable></option></term>
335
 
        <listitem>
336
 
          <para>
337
 
            Specify a different plugin helper directory.  The default
338
 
            is <filename>/lib/mandos/plugin-helpers</filename>, which
339
 
            will exist in the initial <acronym>RAM</acronym> disk
340
 
            environment.  (This will simply be passed to all plugins
341
 
            via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
342
 
            variable.  See <xref linkend="writing_plugins"/>)
343
 
          </para>
344
 
        </listitem>
345
 
      </varlistentry>
346
 
      
347
 
      <varlistentry>
348
320
        <term><option>--config-file
349
321
        <replaceable>FILE</replaceable></option></term>
350
322
        <listitem>
393
365
          </para>
394
366
        </listitem>
395
367
      </varlistentry>
396
 
      
 
368
 
397
369
      <varlistentry>
398
370
        <term><option>--version</option></term>
399
371
        <term><option>-V</option></term>
405
377
      </varlistentry>
406
378
    </variablelist>
407
379
  </refsect1>
408
 
  
 
380
 
409
381
  <refsect1 id="overview">
410
382
    <title>OVERVIEW</title>
411
383
    <xi:include href="overview.xml"/>
431
403
      code will make this plugin-runner output the password from that
432
404
      plugin, stop any other plugins, and exit.
433
405
    </para>
434
 
    
 
406
 
435
407
    <refsect2 id="writing_plugins">
436
408
      <title>WRITING PLUGINS</title>
437
409
      <para>
444
416
        console.
445
417
      </para>
446
418
      <para>
447
 
        If the password is a single-line, manually entered passprase,
448
 
        a final trailing newline character should
449
 
        <emphasis>not</emphasis> be printed.
450
 
      </para>
451
 
      <para>
452
419
        The plugin will run in the initial RAM disk environment, so
453
420
        care must be taken not to depend on any files or running
454
 
        services not available there.  Any helper executables required
455
 
        by the plugin (which are not in the <envar>PATH</envar>) can
456
 
        be placed in the plugin helper directory, the name of which
457
 
        will be made available to the plugin via the
458
 
        <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
 
421
        services not available there.
459
422
      </para>
460
423
      <para>
461
424
        The plugin must exit cleanly and free all allocated resources
504
467
      only passes on its environment to all the plugins.  The
505
468
      environment passed to plugins can be modified using the
506
469
      <option>--global-env</option> and <option>--env-for</option>
507
 
      options.  Also, the <option>--plugin-helper-dir</option> option
508
 
      will affect the environment variable
509
 
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
 
470
      options.
510
471
    </para>
511
472
  </refsect1>
512
473
  
545
506
            </para>
546
507
          </listitem>
547
508
        </varlistentry>
548
 
        <varlistentry>
549
 
          <term><filename class="directory"
550
 
          >/lib/mandos/plugins.d</filename></term>
551
 
          <listitem>
552
 
            <para>
553
 
              The default plugin directory; can be changed by the
554
 
              <option>--plugin-dir</option> option.
555
 
            </para>
556
 
          </listitem>
557
 
        </varlistentry>
558
 
        <varlistentry>
559
 
          <term><filename class="directory"
560
 
          >/lib/mandos/plugin-helpers</filename></term>
561
 
          <listitem>
562
 
            <para>
563
 
              The default plugin helper directory; can be changed by
564
 
              the <option>--plugin-helper-dir</option> option.
565
 
            </para>
566
 
          </listitem>
567
 
        </varlistentry>
568
509
      </variablelist>
569
510
    </para>
570
511
  </refsect1>
575
516
      The <option>--config-file</option> option is ignored when
576
517
      specified from within a configuration file.
577
518
    </para>
578
 
    <xi:include href="bugs.xml"/>
579
519
  </refsect1>
580
520
  
581
521
  <refsect1 id="examples">
624
564
    </informalexample>
625
565
    <informalexample>
626
566
      <para>
627
 
        Read a different configuration file, run plugins from a
628
 
        different directory, specify an alternate plugin helper
629
 
        directory and add two options to the
630
 
        <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>
631
570
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
632
571
      </para>
633
572
      <para>
634
573
 
635
574
<!-- do not wrap this line -->
636
 
<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>
637
576
 
638
577
      </para>
639
578
    </informalexample>
647
586
      non-privileged.  This user and group is then what all plugins
648
587
      will be started as.  Therefore, the only way to run a plugin as
649
588
      a privileged user is to have the set-user-ID or set-group-ID bit
650
 
      set on the plugin executable file (see <citerefentry>
 
589
      set on the plugin executable files (see <citerefentry>
651
590
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
652
591
      </citerefentry>).
653
592
    </para>
671
610
  <refsect1 id="see_also">
672
611
    <title>SEE ALSO</title>
673
612
    <para>
674
 
      <citerefentry><refentrytitle>intro</refentrytitle>
675
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
676
613
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
677
614
      <manvolnum>8</manvolnum></citerefentry>,
678
615
      <citerefentry><refentrytitle>crypttab</refentrytitle>
683
620
      <manvolnum>8</manvolnum></citerefentry>,
684
621
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
685
622
      <manvolnum>8mandos</manvolnum></citerefentry>,
686
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
623
      <citerefentry><refentrytitle>password-request</refentrytitle>
687
624
      <manvolnum>8mandos</manvolnum></citerefentry>
688
625
    </para>
689
626
  </refsect1>