/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

* plugins.d/mandos-client.c: Merge unified printing system.

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 "2011-10-05">
 
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>2011</year>
34
37
      <holder>Teddy Hogeborn</holder>
35
38
      <holder>Björn Påhlsson</holder>
36
39
    </copyright>
37
40
    <xi:include href="legalnotice.xml"/>
38
41
  </refentryinfo>
39
 
 
 
42
  
40
43
  <refmeta>
41
44
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
45
    <manvolnum>8mandos</manvolnum>
45
48
  <refnamediv>
46
49
    <refname><command>&COMMANDNAME;</command></refname>
47
50
    <refpurpose>
48
 
      Run Mandos plugins.  Pass data from first succesful one.
 
51
      Run Mandos plugins, pass data from first to succeed.
49
52
    </refpurpose>
50
53
  </refnamediv>
51
 
 
 
54
  
52
55
  <refsynopsisdiv>
53
56
    <cmdsynopsis>
54
57
      <command>&COMMANDNAME;</command>
55
58
      <group rep="repeat">
56
59
        <arg choice="plain"><option>--global-env=<replaceable
57
 
        >VAR</replaceable><literal>=</literal><replaceable
 
60
        >ENV</replaceable><literal>=</literal><replaceable
58
61
        >value</replaceable></option></arg>
59
62
        <arg choice="plain"><option>-G
60
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
63
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
61
64
        >value</replaceable> </option></arg>
62
65
      </group>
63
66
      <sbr/>
140
143
    <title>DESCRIPTION</title>
141
144
    <para>
142
145
      <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>
 
146
      be specified as a <quote>keyscript</quote> for the root disk in
 
147
      <citerefentry><refentrytitle>crypttab</refentrytitle>
 
148
      <manvolnum>5</manvolnum></citerefentry>.  The aim of this
 
149
      program is therefore to output a password, which then
 
150
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
148
151
      <manvolnum>8</manvolnum></citerefentry> will use to unlock the
149
152
      root disk.
150
153
    </para>
170
173
    <variablelist>
171
174
      <varlistentry>
172
175
        <term><option>--global-env
173
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
176
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
174
177
        >value</replaceable></option></term>
175
178
        <term><option>-G
176
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
179
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
177
180
        >value</replaceable></option></term>
178
181
        <listitem>
179
182
          <para>
247
250
          </para>
248
251
        </listitem>
249
252
      </varlistentry>
250
 
 
 
253
      
251
254
      <varlistentry>
252
255
        <term><option>--disable
253
256
        <replaceable>PLUGIN</replaceable></option></term>
258
261
            Disable the plugin named
259
262
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
260
263
            started.
261
 
          </para>       
 
264
          </para>
262
265
        </listitem>
263
266
      </varlistentry>
264
 
 
 
267
      
265
268
      <varlistentry>
266
269
        <term><option>--enable
267
270
        <replaceable>PLUGIN</replaceable></option></term>
272
275
            Re-enable the plugin named
273
276
            <replaceable>PLUGIN</replaceable>.  This is only useful to
274
277
            undo a previous <option>--disable</option> option, maybe
275
 
            from the config file.
 
278
            from the configuration file.
276
279
          </para>
277
280
        </listitem>
278
281
      </varlistentry>
279
 
 
 
282
      
280
283
      <varlistentry>
281
284
        <term><option>--groupid
282
285
        <replaceable>ID</replaceable></option></term>
289
292
          </para>
290
293
        </listitem>
291
294
      </varlistentry>
292
 
 
 
295
      
293
296
      <varlistentry>
294
297
        <term><option>--userid
295
298
        <replaceable>ID</replaceable></option></term>
302
305
          </para>
303
306
        </listitem>
304
307
      </varlistentry>
305
 
 
 
308
      
306
309
      <varlistentry>
307
310
        <term><option>--plugin-dir
308
311
        <replaceable>DIRECTORY</replaceable></option></term>
365
368
          </para>
366
369
        </listitem>
367
370
      </varlistentry>
368
 
 
 
371
      
369
372
      <varlistentry>
370
373
        <term><option>--version</option></term>
371
374
        <term><option>-V</option></term>
377
380
      </varlistentry>
378
381
    </variablelist>
379
382
  </refsect1>
380
 
 
 
383
  
381
384
  <refsect1 id="overview">
382
385
    <title>OVERVIEW</title>
383
386
    <xi:include href="overview.xml"/>
403
406
      code will make this plugin-runner output the password from that
404
407
      plugin, stop any other plugins, and exit.
405
408
    </para>
406
 
 
 
409
    
407
410
    <refsect2 id="writing_plugins">
408
411
      <title>WRITING PLUGINS</title>
409
412
      <para>
416
419
        console.
417
420
      </para>
418
421
      <para>
 
422
        If the password is a single-line, manually entered passprase,
 
423
        a final trailing newline character should
 
424
        <emphasis>not</emphasis> be printed.
 
425
      </para>
 
426
      <para>
419
427
        The plugin will run in the initial RAM disk environment, so
420
428
        care must be taken not to depend on any files or running
421
429
        services not available there.
428
436
      </para>
429
437
      <para>
430
438
        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.
 
439
        from the standard input, without knowing that no other plugin
 
440
        is also using it.
433
441
      </para>
434
442
      <para>
435
443
        It is useful, but not required, for the plugin to take the
467
475
      only passes on its environment to all the plugins.  The
468
476
      environment passed to plugins can be modified using the
469
477
      <option>--global-env</option> and <option>--env-for</option>
470
 
      optins.
 
478
      options.
471
479
    </para>
472
480
  </refsect1>
473
481
  
510
518
    </para>
511
519
  </refsect1>
512
520
  
513
 
<!--   <refsect1 id="bugs"> -->
514
 
<!--     <title>BUGS</title> -->
515
 
<!--     <para> -->
516
 
<!--     </para> -->
517
 
<!--   </refsect1> -->
 
521
  <refsect1 id="bugs">
 
522
    <title>BUGS</title>
 
523
    <para>
 
524
      The <option>--config-file</option> option is ignored when
 
525
      specified from within a configuration file.
 
526
    </para>
 
527
  </refsect1>
518
528
  
519
529
  <refsect1 id="examples">
520
530
    <title>EXAMPLE</title>
562
572
    </informalexample>
563
573
    <informalexample>
564
574
      <para>
565
 
        Run plugins from a different directory and add a special
566
 
        option to the <citerefentry><refentrytitle
567
 
        >password-request</refentrytitle>
 
575
        Run plugins from a different directory, read a different
 
576
        configuration file, and add two options to the
 
577
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
568
578
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
569
579
      </para>
570
580
      <para>
571
581
 
572
582
<!-- do not wrap this line -->
573
 
<userinput>&COMMANDNAME;  --plugin-dir=plugins.d --options-for=password-request:--keydir=keydir</userinput>
 
583
<userinput>cd /etc/keys/mandos; &COMMANDNAME;  --config-file=/etc/mandos/plugin-runner.conf --plugin-dir /usr/lib/mandos/plugins.d --options-for=mandos-client:--pubkey=pubkey.txt,--seckey=seckey.txt</userinput>
574
584
 
575
585
      </para>
576
586
    </informalexample>
584
594
      non-privileged.  This user and group is then what all plugins
585
595
      will be started as.  Therefore, the only way to run a plugin as
586
596
      a privileged user is to have the set-user-ID or set-group-ID bit
587
 
      set on the plugin executable files (see <citerefentry>
 
597
      set on the plugin executable file (see <citerefentry>
588
598
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
589
599
      </citerefentry>).
590
600
    </para>
591
601
    <para>
592
602
      If this program is used as a keyscript in <citerefentry
593
603
      ><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
 
604
      </citerefentry>, there is a slight risk that if this program
 
605
      fails to work, there might be no way to boot the system except
 
606
      for booting from another media and editing the initial RAM disk
597
607
      image to not run this program.  This is, however, unlikely,
598
608
      since the <citerefentry><refentrytitle
599
609
      >password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
608
618
  <refsect1 id="see_also">
609
619
    <title>SEE ALSO</title>
610
620
    <para>
 
621
      <citerefentry><refentrytitle>intro</refentrytitle>
 
622
      <manvolnum>8mandos</manvolnum></citerefentry>,
611
623
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
612
624
      <manvolnum>8</manvolnum></citerefentry>,
613
625
      <citerefentry><refentrytitle>crypttab</refentrytitle>
618
630
      <manvolnum>8</manvolnum></citerefentry>,
619
631
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
620
632
      <manvolnum>8mandos</manvolnum></citerefentry>,
621
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
633
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
622
634
      <manvolnum>8mandos</manvolnum></citerefentry>
623
635
    </para>
624
636
  </refsect1>