/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 "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
 
        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>
 
567
        Run plugins from a different directory and add two
 
568
        options to the <citerefentry><refentrytitle
 
569
        >password-request</refentrytitle>
603
570
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
604
571
      </para>
605
572
      <para>
606
573
 
607
574
<!-- 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>
 
575
<userinput>&COMMANDNAME;  --plugin-dir=plugins.d --options-for=password-request:--pubkey=keydir/pubkey.txt,--seckey=keydir/seckey.txt</userinput>
609
576
 
610
577
      </para>
611
578
    </informalexample>
619
586
      non-privileged.  This user and group is then what all plugins
620
587
      will be started as.  Therefore, the only way to run a plugin as
621
588
      a privileged user is to have the set-user-ID or set-group-ID bit
622
 
      set on the plugin executable file (see <citerefentry>
 
589
      set on the plugin executable files (see <citerefentry>
623
590
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
624
591
      </citerefentry>).
625
592
    </para>
643
610
  <refsect1 id="see_also">
644
611
    <title>SEE ALSO</title>
645
612
    <para>
646
 
      <citerefentry><refentrytitle>intro</refentrytitle>
647
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
648
613
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
649
614
      <manvolnum>8</manvolnum></citerefentry>,
650
615
      <citerefentry><refentrytitle>crypttab</refentrytitle>
655
620
      <manvolnum>8</manvolnum></citerefentry>,
656
621
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
657
622
      <manvolnum>8mandos</manvolnum></citerefentry>,
658
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
623
      <citerefentry><refentrytitle>password-request</refentrytitle>
659
624
      <manvolnum>8mandos</manvolnum></citerefentry>
660
625
    </para>
661
626
  </refsect1>