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