/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: 2008-09-02 13:04:42 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080902130442-ytnjsmllaph18e20
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
  (BUGS): Commented out.  There are no bugs.
  (EXAMPLE): Added lots of examples.
  (SECURITY): Added text.
  (SEE ALSO): Added "crypttab(5)" and "execve(2)".

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-02">
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>
55
45
  <refnamediv>
56
46
    <refname><command>&COMMANDNAME;</command></refname>
57
47
    <refpurpose>
58
 
      Run Mandos plugins, pass data from first to succeed.
 
48
      Run Mandos plugins.  Pass data from first succesful one.
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/>
153
140
    <title>DESCRIPTION</title>
154
141
    <para>
155
142
      <command>&COMMANDNAME;</command> is a program which is meant to
156
 
      be specified as a <quote>keyscript</quote> for the root disk in
157
 
      <citerefentry><refentrytitle>crypttab</refentrytitle>
158
 
      <manvolnum>5</manvolnum></citerefentry>.  The aim of this
159
 
      program is therefore to output a password, which then
160
 
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
 
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>
161
148
      <manvolnum>8</manvolnum></citerefentry> will use to unlock the
162
149
      root disk.
163
150
    </para>
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>
285
272
            Re-enable the plugin named
286
273
            <replaceable>PLUGIN</replaceable>.  This is only useful to
287
274
            undo a previous <option>--disable</option> option, maybe
288
 
            from the configuration file.
 
275
            from the config file.
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
465
428
      </para>
466
429
      <para>
467
430
        The plugin must not use resources, like for instance reading
468
 
        from the standard input, without knowing that no other plugin
469
 
        is also using it.
 
431
        from the standard input, without knowing that no other plugins
 
432
        are also using it.
470
433
      </para>
471
434
      <para>
472
435
        It is useful, but not required, for the plugin to take the
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
      optins.
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>
571
512
  
572
 
  <refsect1 id="bugs">
573
 
    <title>BUGS</title>
574
 
    <para>
575
 
      The <option>--config-file</option> option is ignored when
576
 
      specified from within a configuration file.
577
 
    </para>
578
 
    <xi:include href="bugs.xml"/>
579
 
  </refsect1>
 
513
<!--   <refsect1 id="bugs"> -->
 
514
<!--     <title>BUGS</title> -->
 
515
<!--     <para> -->
 
516
<!--     </para> -->
 
517
<!--   </refsect1> -->
580
518
  
581
519
  <refsect1 id="examples">
582
520
    <title>EXAMPLE</title>
624
562
    </informalexample>
625
563
    <informalexample>
626
564
      <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>
 
565
        Run plugins from a different directory and add a special
 
566
        option to the <citerefentry><refentrytitle
 
567
        >password-request</refentrytitle>
631
568
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
632
569
      </para>
633
570
      <para>
634
571
 
635
572
<!-- 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>
 
573
<userinput>&COMMANDNAME;  --plugin-dir=plugins.d --options-for=password-request:--keydir=keydir</userinput>
637
574
 
638
575
      </para>
639
576
    </informalexample>
647
584
      non-privileged.  This user and group is then what all plugins
648
585
      will be started as.  Therefore, the only way to run a plugin as
649
586
      a privileged user is to have the set-user-ID or set-group-ID bit
650
 
      set on the plugin executable file (see <citerefentry>
 
587
      set on the plugin executable files (see <citerefentry>
651
588
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
652
589
      </citerefentry>).
653
590
    </para>
654
591
    <para>
655
592
      If this program is used as a keyscript in <citerefentry
656
593
      ><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
657
 
      </citerefentry>, there is a slight risk that if this program
658
 
      fails to work, there might be no way to boot the system except
659
 
      for booting from another media and editing the initial RAM disk
 
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
660
597
      image to not run this program.  This is, however, unlikely,
661
598
      since the <citerefentry><refentrytitle
662
599
      >password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
671
608
  <refsect1 id="see_also">
672
609
    <title>SEE ALSO</title>
673
610
    <para>
674
 
      <citerefentry><refentrytitle>intro</refentrytitle>
675
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
676
611
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
677
612
      <manvolnum>8</manvolnum></citerefentry>,
678
613
      <citerefentry><refentrytitle>crypttab</refentrytitle>
683
618
      <manvolnum>8</manvolnum></citerefentry>,
684
619
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
685
620
      <manvolnum>8mandos</manvolnum></citerefentry>,
686
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
621
      <citerefentry><refentrytitle>password-request</refentrytitle>
687
622
      <manvolnum>8mandos</manvolnum></citerefentry>
688
623
    </para>
689
624
  </refsect1>