/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: 2008-09-02 10:27:08 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080902102708-j5k6ec3lcgkaeipv
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
                     changed short option for "--env-for" to "-E".
                     added new options "--enable" ("-e") and
                     "--config-file".
  (ENVIRONMENT): Added text.
  (FILES): Changed id to "files".  Improved wording and add more text.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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 "2019-02-10">
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
 
      <year>2018</year>
45
 
      <year>2019</year>
46
34
      <holder>Teddy Hogeborn</holder>
47
35
      <holder>Björn Påhlsson</holder>
48
36
    </copyright>
49
37
    <xi:include href="legalnotice.xml"/>
50
38
  </refentryinfo>
51
 
  
 
39
 
52
40
  <refmeta>
53
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
54
42
    <manvolnum>8mandos</manvolnum>
57
45
  <refnamediv>
58
46
    <refname><command>&COMMANDNAME;</command></refname>
59
47
    <refpurpose>
60
 
      Run Mandos plugins, pass data from first to succeed.
 
48
      Run Mandos plugins.  Pass data from first succesful one.
61
49
    </refpurpose>
62
50
  </refnamediv>
63
 
  
 
51
 
64
52
  <refsynopsisdiv>
65
53
    <cmdsynopsis>
66
54
      <command>&COMMANDNAME;</command>
67
55
      <group rep="repeat">
68
56
        <arg choice="plain"><option>--global-env=<replaceable
69
 
        >ENV</replaceable><literal>=</literal><replaceable
 
57
        >VAR</replaceable><literal>=</literal><replaceable
70
58
        >value</replaceable></option></arg>
71
59
        <arg choice="plain"><option>-G
72
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
60
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
73
61
        >value</replaceable> </option></arg>
74
62
      </group>
75
63
      <sbr/>
123
111
      <arg><option>--plugin-dir=<replaceable
124
112
      >DIRECTORY</replaceable></option></arg>
125
113
      <sbr/>
126
 
      <arg><option>--plugin-helper-dir=<replaceable
127
 
      >DIRECTORY</replaceable></option></arg>
128
 
      <sbr/>
129
114
      <arg><option>--config-file=<replaceable
130
115
      >FILE</replaceable></option></arg>
131
116
      <sbr/>
155
140
    <title>DESCRIPTION</title>
156
141
    <para>
157
142
      <command>&COMMANDNAME;</command> is a program which is meant to
158
 
      be specified as a <quote>keyscript</quote> for the root disk in
159
 
      <citerefentry><refentrytitle>crypttab</refentrytitle>
160
 
      <manvolnum>5</manvolnum></citerefentry>.  The aim of this
161
 
      program is therefore to output a password, which then
162
 
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
163
 
      <manvolnum>8</manvolnum></citerefentry> will use to unlock the
164
 
      root disk.
 
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>
 
148
      <manvolnum>8</manvolnum></citerefentry> will use to try and
 
149
      unlock the root disk.
165
150
    </para>
166
151
    <para>
167
152
      This program is not meant to be invoked directly, but can be in
185
170
    <variablelist>
186
171
      <varlistentry>
187
172
        <term><option>--global-env
188
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
173
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
189
174
        >value</replaceable></option></term>
190
 
        <term><option>-G
191
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
175
        <term><option>-e
 
176
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
192
177
        >value</replaceable></option></term>
193
178
        <listitem>
194
179
          <para>
204
189
        <replaceable>PLUGIN</replaceable><literal>:</literal
205
190
        ><replaceable>ENV</replaceable><literal>=</literal
206
191
        ><replaceable>value</replaceable></option></term>
207
 
        <term><option>-E
 
192
        <term><option>-f
208
193
        <replaceable>PLUGIN</replaceable><literal>:</literal
209
194
        ><replaceable>ENV</replaceable><literal>=</literal
210
195
        ><replaceable>value</replaceable></option></term>
230
215
            <replaceable>OPTIONS</replaceable> is a comma separated
231
216
            list of options.  This is not a very useful option, except
232
217
            for specifying the <quote><option>--debug</option></quote>
233
 
            option to all plugins.
 
218
            for all plugins.
234
219
          </para>
235
220
        </listitem>
236
221
      </varlistentry>
256
241
            <option>--bar</option> with the option argument
257
242
            <quote>baz</quote> is either
258
243
            <userinput>--options-for=foo:--bar=baz</userinput> or
259
 
            <userinput>--options-for=foo:--bar,baz</userinput>.  Using
260
 
            <userinput>--options-for="foo:--bar baz"</userinput>. will
261
 
            <emphasis>not</emphasis> work.
 
244
            <userinput>--options-for=foo:--bar,baz</userinput>, but
 
245
            <emphasis>not</emphasis>
 
246
            <userinput>--options-for="foo:--bar baz"</userinput>.
262
247
          </para>
263
248
        </listitem>
264
249
      </varlistentry>
265
 
      
 
250
 
266
251
      <varlistentry>
267
252
        <term><option>--disable
268
253
        <replaceable>PLUGIN</replaceable></option></term>
273
258
            Disable the plugin named
274
259
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
275
260
            started.
276
 
          </para>
 
261
          </para>       
277
262
        </listitem>
278
263
      </varlistentry>
279
 
      
 
264
 
280
265
      <varlistentry>
281
266
        <term><option>--enable
282
267
        <replaceable>PLUGIN</replaceable></option></term>
287
272
            Re-enable the plugin named
288
273
            <replaceable>PLUGIN</replaceable>.  This is only useful to
289
274
            undo a previous <option>--disable</option> option, maybe
290
 
            from the configuration file.
 
275
            from the config file.
291
276
          </para>
292
277
        </listitem>
293
278
      </varlistentry>
294
 
      
 
279
 
295
280
      <varlistentry>
296
281
        <term><option>--groupid
297
282
        <replaceable>ID</replaceable></option></term>
304
289
          </para>
305
290
        </listitem>
306
291
      </varlistentry>
307
 
      
 
292
 
308
293
      <varlistentry>
309
294
        <term><option>--userid
310
295
        <replaceable>ID</replaceable></option></term>
317
302
          </para>
318
303
        </listitem>
319
304
      </varlistentry>
320
 
      
 
305
 
321
306
      <varlistentry>
322
307
        <term><option>--plugin-dir
323
308
        <replaceable>DIRECTORY</replaceable></option></term>
332
317
      </varlistentry>
333
318
      
334
319
      <varlistentry>
335
 
        <term><option>--plugin-helper-dir
336
 
        <replaceable>DIRECTORY</replaceable></option></term>
337
 
        <listitem>
338
 
          <para>
339
 
            Specify a different plugin helper directory.  The default
340
 
            is <filename>/lib/mandos/plugin-helpers</filename>, which
341
 
            will exist in the initial <acronym>RAM</acronym> disk
342
 
            environment.  (This will simply be passed to all plugins
343
 
            via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
344
 
            variable.  See <xref linkend="writing_plugins"/>)
345
 
          </para>
346
 
        </listitem>
347
 
      </varlistentry>
348
 
      
349
 
      <varlistentry>
350
320
        <term><option>--config-file
351
321
        <replaceable>FILE</replaceable></option></term>
352
322
        <listitem>
395
365
          </para>
396
366
        </listitem>
397
367
      </varlistentry>
398
 
      
 
368
 
399
369
      <varlistentry>
400
370
        <term><option>--version</option></term>
401
371
        <term><option>-V</option></term>
407
377
      </varlistentry>
408
378
    </variablelist>
409
379
  </refsect1>
410
 
  
 
380
 
411
381
  <refsect1 id="overview">
412
382
    <title>OVERVIEW</title>
413
383
    <xi:include href="overview.xml"/>
433
403
      code will make this plugin-runner output the password from that
434
404
      plugin, stop any other plugins, and exit.
435
405
    </para>
436
 
    
437
 
    <refsect2 id="writing_plugins">
438
 
      <title>WRITING PLUGINS</title>
439
 
      <para>
440
 
        A plugin is simply a program which prints a password to its
441
 
        standard output and then exits with a successful (zero) exit
442
 
        status.  If the exit status is not zero, any output on
443
 
        standard output will be ignored by the plugin runner.  Any
444
 
        output on its standard error channel will simply be passed to
445
 
        the standard error of the plugin runner, usually the system
446
 
        console.
447
 
      </para>
448
 
      <para>
449
 
        If the password is a single-line, manually entered passprase,
450
 
        a final trailing newline character should
451
 
        <emphasis>not</emphasis> be printed.
452
 
      </para>
453
 
      <para>
454
 
        The plugin will run in the initial RAM disk environment, so
455
 
        care must be taken not to depend on any files or running
456
 
        services not available there.  Any helper executables required
457
 
        by the plugin (which are not in the <envar>PATH</envar>) can
458
 
        be placed in the plugin helper directory, the name of which
459
 
        will be made available to the plugin via the
460
 
        <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
461
 
      </para>
462
 
      <para>
463
 
        The plugin must exit cleanly and free all allocated resources
464
 
        upon getting the TERM signal, since this is what the plugin
465
 
        runner uses to stop all other plugins when one plugin has
466
 
        output a password and exited cleanly.
467
 
      </para>
468
 
      <para>
469
 
        The plugin must not use resources, like for instance reading
470
 
        from the standard input, without knowing that no other plugin
471
 
        is also using it.
472
 
      </para>
473
 
      <para>
474
 
        It is useful, but not required, for the plugin to take the
475
 
        <option>--debug</option> option.
476
 
      </para>
477
 
    </refsect2>
478
406
  </refsect1>
479
407
  
480
408
  <refsect1 id="fallback">
506
434
      only passes on its environment to all the plugins.  The
507
435
      environment passed to plugins can be modified using the
508
436
      <option>--global-env</option> and <option>--env-for</option>
509
 
      options.  Also, the <option>--plugin-helper-dir</option> option
510
 
      will affect the environment variable
511
 
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
 
437
      optins.
512
438
    </para>
513
439
  </refsect1>
514
440
  
547
473
            </para>
548
474
          </listitem>
549
475
        </varlistentry>
550
 
        <varlistentry>
551
 
          <term><filename class="directory"
552
 
          >/lib/mandos/plugins.d</filename></term>
553
 
          <listitem>
554
 
            <para>
555
 
              The default plugin directory; can be changed by the
556
 
              <option>--plugin-dir</option> option.
557
 
            </para>
558
 
          </listitem>
559
 
        </varlistentry>
560
 
        <varlistentry>
561
 
          <term><filename class="directory"
562
 
          >/lib/mandos/plugin-helpers</filename></term>
563
 
          <listitem>
564
 
            <para>
565
 
              The default plugin helper directory; can be changed by
566
 
              the <option>--plugin-helper-dir</option> option.
567
 
            </para>
568
 
          </listitem>
569
 
        </varlistentry>
570
476
      </variablelist>
571
477
    </para>
572
478
  </refsect1>
574
480
  <refsect1 id="bugs">
575
481
    <title>BUGS</title>
576
482
    <para>
577
 
      The <option>--config-file</option> option is ignored when
578
 
      specified from within a configuration file.
579
483
    </para>
580
 
    <xi:include href="bugs.xml"/>
581
484
  </refsect1>
582
485
  
583
486
  <refsect1 id="examples">
584
487
    <title>EXAMPLE</title>
585
 
    <informalexample>
586
 
      <para>
587
 
        Normal invocation needs no options:
588
 
      </para>
589
 
      <para>
590
 
        <userinput>&COMMANDNAME;</userinput>
591
 
      </para>
592
 
    </informalexample>
593
 
    <informalexample>
594
 
      <para>
595
 
        Run the program, but not the plugins, in debug mode:
596
 
      </para>
597
 
      <para>
598
 
        
599
 
        <!-- do not wrap this line -->
600
 
        <userinput>&COMMANDNAME; --debug</userinput>
601
 
        
602
 
      </para>
603
 
    </informalexample>
604
 
    <informalexample>
605
 
      <para>
606
 
        Run all plugins, but run the <quote>foo</quote> plugin in
607
 
        debug mode:
608
 
      </para>
609
 
      <para>
610
 
        
611
 
        <!-- do not wrap this line -->
612
 
        <userinput>&COMMANDNAME; --options-for=foo:--debug</userinput>
613
 
        
614
 
      </para>
615
 
    </informalexample>
616
 
    <informalexample>
617
 
      <para>
618
 
        Run all plugins, but not the program, in debug mode:
619
 
      </para>
620
 
      <para>
621
 
        
622
 
        <!-- do not wrap this line -->
623
 
        <userinput>&COMMANDNAME; --global-options=--debug</userinput>
624
 
        
625
 
      </para>
626
 
    </informalexample>
627
 
    <informalexample>
628
 
      <para>
629
 
        Read a different configuration file, run plugins from a
630
 
        different directory, specify an alternate plugin helper
631
 
        directory and add two options to the
632
 
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
633
 
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
634
 
      </para>
635
 
      <para>
636
 
 
637
 
<!-- do not wrap this line -->
638
 
<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,--tls-pubkey=tls-pubkey.pem,--tls-privkey=tls-privkey.pem</userinput>
639
 
 
640
 
      </para>
641
 
    </informalexample>
 
488
    <para>
 
489
    </para>
642
490
  </refsect1>
 
491
  
643
492
  <refsect1 id="security">
644
493
    <title>SECURITY</title>
645
494
    <para>
646
 
      This program will, when starting, try to switch to another user.
647
 
      If it is started as root, it will succeed, and will by default
648
 
      switch to user and group 65534, which are assumed to be
649
 
      non-privileged.  This user and group is then what all plugins
650
 
      will be started as.  Therefore, the only way to run a plugin as
651
 
      a privileged user is to have the set-user-ID or set-group-ID bit
652
 
      set on the plugin executable file (see <citerefentry>
653
 
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
654
 
      </citerefentry>).
655
 
    </para>
656
 
    <para>
657
 
      If this program is used as a keyscript in <citerefentry
658
 
      ><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
659
 
      </citerefentry>, there is a slight risk that if this program
660
 
      fails to work, there might be no way to boot the system except
661
 
      for booting from another media and editing the initial RAM disk
662
 
      image to not run this program.  This is, however, unlikely,
663
 
      since the <citerefentry><refentrytitle
664
 
      >password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
665
 
      </citerefentry> plugin will read a password from the console in
666
 
      case of failure of the other plugins, and this plugin runner
667
 
      will also, in case of catastrophic failure, itself fall back to
668
 
      asking and outputting a password on the console (see <xref
669
 
      linkend="fallback"/>).
670
495
    </para>
671
496
  </refsect1>
672
497
  
673
498
  <refsect1 id="see_also">
674
499
    <title>SEE ALSO</title>
675
500
    <para>
676
 
      <citerefentry><refentrytitle>intro</refentrytitle>
677
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
678
501
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
679
502
      <manvolnum>8</manvolnum></citerefentry>,
680
 
      <citerefentry><refentrytitle>crypttab</refentrytitle>
681
 
      <manvolnum>5</manvolnum></citerefentry>,
682
 
      <citerefentry><refentrytitle>execve</refentrytitle>
683
 
      <manvolnum>2</manvolnum></citerefentry>,
684
503
      <citerefentry><refentrytitle>mandos</refentrytitle>
685
504
      <manvolnum>8</manvolnum></citerefentry>,
686
505
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
687
506
      <manvolnum>8mandos</manvolnum></citerefentry>,
688
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
507
      <citerefentry><refentrytitle>password-request</refentrytitle>
689
508
      <manvolnum>8mandos</manvolnum></citerefentry>
690
509
    </para>
691
510
  </refsect1>