/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: 2017-08-20 14:41:20 UTC
  • Revision ID: teddy@recompile.se-20170820144120-ee0hsyhvo1geg8ms
Handle multiple lines better in cryptroot file.

* initramfs-tools-script: Avoid running plugin-runner more than once
  if the root file system device is specially marked in the cryptroot
  file.  Also never run plugin-runner for a resume (usually swap)
  device.

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 "2017-02-23">
 
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>
 
43
      <year>2017</year>
34
44
      <holder>Teddy Hogeborn</holder>
35
45
      <holder>Björn Påhlsson</holder>
36
46
    </copyright>
37
47
    <xi:include href="legalnotice.xml"/>
38
48
  </refentryinfo>
39
 
 
 
49
  
40
50
  <refmeta>
41
51
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
52
    <manvolnum>8mandos</manvolnum>
45
55
  <refnamediv>
46
56
    <refname><command>&COMMANDNAME;</command></refname>
47
57
    <refpurpose>
48
 
      Run Mandos plugins.  Pass data from first succesful one.
 
58
      Run Mandos plugins, pass data from first to succeed.
49
59
    </refpurpose>
50
60
  </refnamediv>
51
 
 
 
61
  
52
62
  <refsynopsisdiv>
53
63
    <cmdsynopsis>
54
64
      <command>&COMMANDNAME;</command>
55
65
      <group rep="repeat">
56
66
        <arg choice="plain"><option>--global-env=<replaceable
57
 
        >VAR</replaceable><literal>=</literal><replaceable
 
67
        >ENV</replaceable><literal>=</literal><replaceable
58
68
        >value</replaceable></option></arg>
59
69
        <arg choice="plain"><option>-G
60
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
70
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
61
71
        >value</replaceable> </option></arg>
62
72
      </group>
63
73
      <sbr/>
111
121
      <arg><option>--plugin-dir=<replaceable
112
122
      >DIRECTORY</replaceable></option></arg>
113
123
      <sbr/>
 
124
      <arg><option>--plugin-helper-dir=<replaceable
 
125
      >DIRECTORY</replaceable></option></arg>
 
126
      <sbr/>
114
127
      <arg><option>--config-file=<replaceable
115
128
      >FILE</replaceable></option></arg>
116
129
      <sbr/>
140
153
    <title>DESCRIPTION</title>
141
154
    <para>
142
155
      <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>
 
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>
148
161
      <manvolnum>8</manvolnum></citerefentry> will use to unlock the
149
162
      root disk.
150
163
    </para>
170
183
    <variablelist>
171
184
      <varlistentry>
172
185
        <term><option>--global-env
173
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
186
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
174
187
        >value</replaceable></option></term>
175
188
        <term><option>-G
176
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
189
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
177
190
        >value</replaceable></option></term>
178
191
        <listitem>
179
192
          <para>
247
260
          </para>
248
261
        </listitem>
249
262
      </varlistentry>
250
 
 
 
263
      
251
264
      <varlistentry>
252
265
        <term><option>--disable
253
266
        <replaceable>PLUGIN</replaceable></option></term>
258
271
            Disable the plugin named
259
272
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
260
273
            started.
261
 
          </para>       
 
274
          </para>
262
275
        </listitem>
263
276
      </varlistentry>
264
 
 
 
277
      
265
278
      <varlistentry>
266
279
        <term><option>--enable
267
280
        <replaceable>PLUGIN</replaceable></option></term>
272
285
            Re-enable the plugin named
273
286
            <replaceable>PLUGIN</replaceable>.  This is only useful to
274
287
            undo a previous <option>--disable</option> option, maybe
275
 
            from the config file.
 
288
            from the configuration file.
276
289
          </para>
277
290
        </listitem>
278
291
      </varlistentry>
279
 
 
 
292
      
280
293
      <varlistentry>
281
294
        <term><option>--groupid
282
295
        <replaceable>ID</replaceable></option></term>
289
302
          </para>
290
303
        </listitem>
291
304
      </varlistentry>
292
 
 
 
305
      
293
306
      <varlistentry>
294
307
        <term><option>--userid
295
308
        <replaceable>ID</replaceable></option></term>
302
315
          </para>
303
316
        </listitem>
304
317
      </varlistentry>
305
 
 
 
318
      
306
319
      <varlistentry>
307
320
        <term><option>--plugin-dir
308
321
        <replaceable>DIRECTORY</replaceable></option></term>
317
330
      </varlistentry>
318
331
      
319
332
      <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>
320
348
        <term><option>--config-file
321
349
        <replaceable>FILE</replaceable></option></term>
322
350
        <listitem>
365
393
          </para>
366
394
        </listitem>
367
395
      </varlistentry>
368
 
 
 
396
      
369
397
      <varlistentry>
370
398
        <term><option>--version</option></term>
371
399
        <term><option>-V</option></term>
377
405
      </varlistentry>
378
406
    </variablelist>
379
407
  </refsect1>
380
 
 
 
408
  
381
409
  <refsect1 id="overview">
382
410
    <title>OVERVIEW</title>
383
411
    <xi:include href="overview.xml"/>
403
431
      code will make this plugin-runner output the password from that
404
432
      plugin, stop any other plugins, and exit.
405
433
    </para>
406
 
 
 
434
    
407
435
    <refsect2 id="writing_plugins">
408
436
      <title>WRITING PLUGINS</title>
409
437
      <para>
416
444
        console.
417
445
      </para>
418
446
      <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>
419
452
        The plugin will run in the initial RAM disk environment, so
420
453
        care must be taken not to depend on any files or running
421
 
        services not available there.
 
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.
422
459
      </para>
423
460
      <para>
424
461
        The plugin must exit cleanly and free all allocated resources
428
465
      </para>
429
466
      <para>
430
467
        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.
 
468
        from the standard input, without knowing that no other plugin
 
469
        is also using it.
433
470
      </para>
434
471
      <para>
435
472
        It is useful, but not required, for the plugin to take the
467
504
      only passes on its environment to all the plugins.  The
468
505
      environment passed to plugins can be modified using the
469
506
      <option>--global-env</option> and <option>--env-for</option>
470
 
      optins.
 
507
      options.  Also, the <option>--plugin-helper-dir</option> option
 
508
      will affect the environment variable
 
509
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
471
510
    </para>
472
511
  </refsect1>
473
512
  
506
545
            </para>
507
546
          </listitem>
508
547
        </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>
509
568
      </variablelist>
510
569
    </para>
511
570
  </refsect1>
512
571
  
513
 
<!--   <refsect1 id="bugs"> -->
514
 
<!--     <title>BUGS</title> -->
515
 
<!--     <para> -->
516
 
<!--     </para> -->
517
 
<!--   </refsect1> -->
 
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>
518
580
  
519
581
  <refsect1 id="examples">
520
582
    <title>EXAMPLE</title>
562
624
    </informalexample>
563
625
    <informalexample>
564
626
      <para>
565
 
        Run plugins from a different directory and add a special
566
 
        option to the <citerefentry><refentrytitle
567
 
        >password-request</refentrytitle>
 
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>
568
631
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
569
632
      </para>
570
633
      <para>
571
634
 
572
635
<!-- do not wrap this line -->
573
 
<userinput>&COMMANDNAME;  --plugin-dir=plugins.d --options-for=password-request:--keydir=keydir</userinput>
 
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>
574
637
 
575
638
      </para>
576
639
    </informalexample>
584
647
      non-privileged.  This user and group is then what all plugins
585
648
      will be started as.  Therefore, the only way to run a plugin as
586
649
      a privileged user is to have the set-user-ID or set-group-ID bit
587
 
      set on the plugin executable files (see <citerefentry>
 
650
      set on the plugin executable file (see <citerefentry>
588
651
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
589
652
      </citerefentry>).
590
653
    </para>
591
654
    <para>
592
655
      If this program is used as a keyscript in <citerefentry
593
656
      ><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
 
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
597
660
      image to not run this program.  This is, however, unlikely,
598
661
      since the <citerefentry><refentrytitle
599
662
      >password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
608
671
  <refsect1 id="see_also">
609
672
    <title>SEE ALSO</title>
610
673
    <para>
 
674
      <citerefentry><refentrytitle>intro</refentrytitle>
 
675
      <manvolnum>8mandos</manvolnum></citerefentry>,
611
676
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
612
677
      <manvolnum>8</manvolnum></citerefentry>,
613
678
      <citerefentry><refentrytitle>crypttab</refentrytitle>
618
683
      <manvolnum>8</manvolnum></citerefentry>,
619
684
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
620
685
      <manvolnum>8mandos</manvolnum></citerefentry>,
621
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
686
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
622
687
      <manvolnum>8mandos</manvolnum></citerefentry>
623
688
    </para>
624
689
  </refsect1>