/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: 2016-02-29 21:28:39 UTC
  • Revision ID: teddy@recompile.se-20160229212839-hoz3rw1us3uds68n
Tags: version-1.7.3-1
* Makefile (version): Changed to "1.7.3".
* NEWS (Version 1.7.3): New entry.
* debian/changelog (1.7.3-1): - '' -

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">
5
4
<!ENTITY COMMANDNAME "plugin-runner">
6
 
<!ENTITY TIMESTAMP "2008-09-02">
 
5
<!ENTITY TIMESTAMP "2016-02-28">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
    <title>Mandos Manual</title>
12
13
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
18
19
        <firstname>Björn</firstname>
19
20
        <surname>Påhlsson</surname>
20
21
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
22
23
        </address>
23
24
      </author>
24
25
      <author>
25
26
        <firstname>Teddy</firstname>
26
27
        <surname>Hogeborn</surname>
27
28
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
29
30
        </address>
30
31
      </author>
31
32
    </authorgroup>
32
33
    <copyright>
33
34
      <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>
34
43
      <holder>Teddy Hogeborn</holder>
35
44
      <holder>Björn Påhlsson</holder>
36
45
    </copyright>
37
46
    <xi:include href="legalnotice.xml"/>
38
47
  </refentryinfo>
39
 
 
 
48
  
40
49
  <refmeta>
41
50
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
51
    <manvolnum>8mandos</manvolnum>
45
54
  <refnamediv>
46
55
    <refname><command>&COMMANDNAME;</command></refname>
47
56
    <refpurpose>
48
 
      Run Mandos plugins.  Pass data from first succesful one.
 
57
      Run Mandos plugins, pass data from first to succeed.
49
58
    </refpurpose>
50
59
  </refnamediv>
51
 
 
 
60
  
52
61
  <refsynopsisdiv>
53
62
    <cmdsynopsis>
54
63
      <command>&COMMANDNAME;</command>
55
64
      <group rep="repeat">
56
65
        <arg choice="plain"><option>--global-env=<replaceable
57
 
        >VAR</replaceable><literal>=</literal><replaceable
 
66
        >ENV</replaceable><literal>=</literal><replaceable
58
67
        >value</replaceable></option></arg>
59
68
        <arg choice="plain"><option>-G
60
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
69
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
61
70
        >value</replaceable> </option></arg>
62
71
      </group>
63
72
      <sbr/>
111
120
      <arg><option>--plugin-dir=<replaceable
112
121
      >DIRECTORY</replaceable></option></arg>
113
122
      <sbr/>
 
123
      <arg><option>--plugin-helper-dir=<replaceable
 
124
      >DIRECTORY</replaceable></option></arg>
 
125
      <sbr/>
114
126
      <arg><option>--config-file=<replaceable
115
127
      >FILE</replaceable></option></arg>
116
128
      <sbr/>
140
152
    <title>DESCRIPTION</title>
141
153
    <para>
142
154
      <command>&COMMANDNAME;</command> is a program which is meant to
143
 
      be specified as <quote>keyscript</quote> in <citerefentry>
144
 
      <refentrytitle>crypttab</refentrytitle>
145
 
      <manvolnum>5</manvolnum></citerefentry> for the root disk.  The
146
 
      aim of this program is therefore to output a password, which
147
 
      then <citerefentry><refentrytitle>cryptsetup</refentrytitle>
 
155
      be specified as a <quote>keyscript</quote> for the root disk in
 
156
      <citerefentry><refentrytitle>crypttab</refentrytitle>
 
157
      <manvolnum>5</manvolnum></citerefentry>.  The aim of this
 
158
      program is therefore to output a password, which then
 
159
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
148
160
      <manvolnum>8</manvolnum></citerefentry> will use to unlock the
149
161
      root disk.
150
162
    </para>
170
182
    <variablelist>
171
183
      <varlistentry>
172
184
        <term><option>--global-env
173
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
185
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
174
186
        >value</replaceable></option></term>
175
187
        <term><option>-G
176
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
188
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
177
189
        >value</replaceable></option></term>
178
190
        <listitem>
179
191
          <para>
247
259
          </para>
248
260
        </listitem>
249
261
      </varlistentry>
250
 
 
 
262
      
251
263
      <varlistentry>
252
264
        <term><option>--disable
253
265
        <replaceable>PLUGIN</replaceable></option></term>
258
270
            Disable the plugin named
259
271
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
260
272
            started.
261
 
          </para>       
 
273
          </para>
262
274
        </listitem>
263
275
      </varlistentry>
264
 
 
 
276
      
265
277
      <varlistentry>
266
278
        <term><option>--enable
267
279
        <replaceable>PLUGIN</replaceable></option></term>
272
284
            Re-enable the plugin named
273
285
            <replaceable>PLUGIN</replaceable>.  This is only useful to
274
286
            undo a previous <option>--disable</option> option, maybe
275
 
            from the config file.
 
287
            from the configuration file.
276
288
          </para>
277
289
        </listitem>
278
290
      </varlistentry>
279
 
 
 
291
      
280
292
      <varlistentry>
281
293
        <term><option>--groupid
282
294
        <replaceable>ID</replaceable></option></term>
289
301
          </para>
290
302
        </listitem>
291
303
      </varlistentry>
292
 
 
 
304
      
293
305
      <varlistentry>
294
306
        <term><option>--userid
295
307
        <replaceable>ID</replaceable></option></term>
302
314
          </para>
303
315
        </listitem>
304
316
      </varlistentry>
305
 
 
 
317
      
306
318
      <varlistentry>
307
319
        <term><option>--plugin-dir
308
320
        <replaceable>DIRECTORY</replaceable></option></term>
317
329
      </varlistentry>
318
330
      
319
331
      <varlistentry>
 
332
        <term><option>--plugin-helper-dir
 
333
        <replaceable>DIRECTORY</replaceable></option></term>
 
334
        <listitem>
 
335
          <para>
 
336
            Specify a different plugin helper directory.  The default
 
337
            is <filename>/lib/mandos/plugin-helpers</filename>, which
 
338
            will exist in the initial <acronym>RAM</acronym> disk
 
339
            environment.  (This will simply be passed to all plugins
 
340
            via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
 
341
            variable.  See <xref linkend="writing_plugins"/>)
 
342
          </para>
 
343
        </listitem>
 
344
      </varlistentry>
 
345
      
 
346
      <varlistentry>
320
347
        <term><option>--config-file
321
348
        <replaceable>FILE</replaceable></option></term>
322
349
        <listitem>
365
392
          </para>
366
393
        </listitem>
367
394
      </varlistentry>
368
 
 
 
395
      
369
396
      <varlistentry>
370
397
        <term><option>--version</option></term>
371
398
        <term><option>-V</option></term>
377
404
      </varlistentry>
378
405
    </variablelist>
379
406
  </refsect1>
380
 
 
 
407
  
381
408
  <refsect1 id="overview">
382
409
    <title>OVERVIEW</title>
383
410
    <xi:include href="overview.xml"/>
403
430
      code will make this plugin-runner output the password from that
404
431
      plugin, stop any other plugins, and exit.
405
432
    </para>
406
 
 
 
433
    
407
434
    <refsect2 id="writing_plugins">
408
435
      <title>WRITING PLUGINS</title>
409
436
      <para>
416
443
        console.
417
444
      </para>
418
445
      <para>
 
446
        If the password is a single-line, manually entered passprase,
 
447
        a final trailing newline character should
 
448
        <emphasis>not</emphasis> be printed.
 
449
      </para>
 
450
      <para>
419
451
        The plugin will run in the initial RAM disk environment, so
420
452
        care must be taken not to depend on any files or running
421
 
        services not available there.
 
453
        services not available there.  Any helper executables required
 
454
        by the plugin (which are not in the <envar>PATH</envar>) can
 
455
        be placed in the plugin helper directory, the name of which
 
456
        will be made available to the plugin via the
 
457
        <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
422
458
      </para>
423
459
      <para>
424
460
        The plugin must exit cleanly and free all allocated resources
428
464
      </para>
429
465
      <para>
430
466
        The plugin must not use resources, like for instance reading
431
 
        from the standard input, without knowing that no other plugins
432
 
        are also using it.
 
467
        from the standard input, without knowing that no other plugin
 
468
        is also using it.
433
469
      </para>
434
470
      <para>
435
471
        It is useful, but not required, for the plugin to take the
467
503
      only passes on its environment to all the plugins.  The
468
504
      environment passed to plugins can be modified using the
469
505
      <option>--global-env</option> and <option>--env-for</option>
470
 
      optins.
 
506
      options.  Also, the <option>--plugin-helper-dir</option> option
 
507
      will affect the environment variable
 
508
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
471
509
    </para>
472
510
  </refsect1>
473
511
  
510
548
    </para>
511
549
  </refsect1>
512
550
  
513
 
<!--   <refsect1 id="bugs"> -->
514
 
<!--     <title>BUGS</title> -->
515
 
<!--     <para> -->
516
 
<!--     </para> -->
517
 
<!--   </refsect1> -->
 
551
  <refsect1 id="bugs">
 
552
    <title>BUGS</title>
 
553
    <para>
 
554
      The <option>--config-file</option> option is ignored when
 
555
      specified from within a configuration file.
 
556
    </para>
 
557
  </refsect1>
518
558
  
519
559
  <refsect1 id="examples">
520
560
    <title>EXAMPLE</title>
562
602
    </informalexample>
563
603
    <informalexample>
564
604
      <para>
565
 
        Run plugins from a different directory and add a special
566
 
        option to the <citerefentry><refentrytitle
567
 
        >password-request</refentrytitle>
 
605
        Read a different configuration file, run plugins from a
 
606
        different directory, specify an alternate plugin helper
 
607
        directory and add two options to the
 
608
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
568
609
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
569
610
      </para>
570
611
      <para>
571
612
 
572
613
<!-- do not wrap this line -->
573
 
<userinput>&COMMANDNAME;  --plugin-dir=plugins.d --options-for=password-request:--keydir=keydir</userinput>
 
614
<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>
574
615
 
575
616
      </para>
576
617
    </informalexample>
584
625
      non-privileged.  This user and group is then what all plugins
585
626
      will be started as.  Therefore, the only way to run a plugin as
586
627
      a privileged user is to have the set-user-ID or set-group-ID bit
587
 
      set on the plugin executable files (see <citerefentry>
 
628
      set on the plugin executable file (see <citerefentry>
588
629
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
589
630
      </citerefentry>).
590
631
    </para>
591
632
    <para>
592
633
      If this program is used as a keyscript in <citerefentry
593
634
      ><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
594
 
      </citerefentry>, there is a risk that if this program fails to
595
 
      work, there might be no way to boot the system except for
596
 
      booting from another media and editing the initial RAM disk
 
635
      </citerefentry>, there is a slight risk that if this program
 
636
      fails to work, there might be no way to boot the system except
 
637
      for booting from another media and editing the initial RAM disk
597
638
      image to not run this program.  This is, however, unlikely,
598
639
      since the <citerefentry><refentrytitle
599
640
      >password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
608
649
  <refsect1 id="see_also">
609
650
    <title>SEE ALSO</title>
610
651
    <para>
 
652
      <citerefentry><refentrytitle>intro</refentrytitle>
 
653
      <manvolnum>8mandos</manvolnum></citerefentry>,
611
654
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
612
655
      <manvolnum>8</manvolnum></citerefentry>,
613
656
      <citerefentry><refentrytitle>crypttab</refentrytitle>
618
661
      <manvolnum>8</manvolnum></citerefentry>,
619
662
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
620
663
      <manvolnum>8mandos</manvolnum></citerefentry>,
621
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
664
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
622
665
      <manvolnum>8mandos</manvolnum></citerefentry>
623
666
    </para>
624
667
  </refsect1>