/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-01 16:53:17 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080901165317-77dccp81zyqimt2j
* plugin-runner.c (add_environment): Override existing environment
                                     variables when asked to do so.
                                     All callers changed.
  (main): Removed old argp.args_doc string.  Parse argument file
          before normal command line arguments.  Use ARGP_IN_ORDER
          flag in both calls to argp_parse.  Do not strdup() strings
          to be sent to add_environment().

* plugin-runner.xml (OPTIONS): Document "--global-env" and "--envs-for".
  (FILES): Note that the config file is parsed before the command line
           options.

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 "2019-07-26">
6
 
<!ENTITY % common SYSTEM "common.ent">
7
 
%common;
 
6
<!ENTITY TIMESTAMP "2008-09-01">
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
 
        <arg choice="plain"><option>-G
72
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
59
        <arg choice="plain"><option>-e
 
60
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
73
61
        >value</replaceable> </option></arg>
74
62
      </group>
75
63
      <sbr/>
78
66
        >PLUGIN</replaceable><literal>:</literal><replaceable
79
67
        >ENV</replaceable><literal>=</literal><replaceable
80
68
        >value</replaceable></option></arg>
81
 
        <arg choice="plain"><option>-E<replaceable>
 
69
        <arg choice="plain"><option>-f<replaceable>
82
70
        PLUGIN</replaceable><literal>:</literal><replaceable
83
71
        >ENV</replaceable><literal>=</literal><replaceable
84
72
        >value</replaceable> </option></arg>
95
83
        <arg choice="plain"><option>--options-for=<replaceable
96
84
        >PLUGIN</replaceable><literal>:</literal><replaceable
97
85
        >OPTIONS</replaceable></option></arg>
98
 
        <arg choice="plain"><option>-o<replaceable>
 
86
        <arg choice="plain"><option>-f<replaceable>
99
87
        PLUGIN</replaceable><literal>:</literal><replaceable
100
88
        >OPTIONS</replaceable> </option></arg>
101
89
      </group>
107
95
        <replaceable>PLUGIN</replaceable> </option></arg>
108
96
      </group>
109
97
      <sbr/>
110
 
      <group rep="repeat">
111
 
        <arg choice="plain"><option>--enable=<replaceable
112
 
        >PLUGIN</replaceable></option></arg>
113
 
        <arg choice="plain"><option>-e
114
 
        <replaceable>PLUGIN</replaceable> </option></arg>
115
 
      </group>
116
 
      <sbr/>
117
98
      <arg><option>--groupid=<replaceable
118
99
      >ID</replaceable></option></arg>
119
100
      <sbr/>
123
104
      <arg><option>--plugin-dir=<replaceable
124
105
      >DIRECTORY</replaceable></option></arg>
125
106
      <sbr/>
126
 
      <arg><option>--plugin-helper-dir=<replaceable
127
 
      >DIRECTORY</replaceable></option></arg>
128
 
      <sbr/>
129
 
      <arg><option>--config-file=<replaceable
130
 
      >FILE</replaceable></option></arg>
131
 
      <sbr/>
132
107
      <arg><option>--debug</option></arg>
133
108
    </cmdsynopsis>
134
109
    <cmdsynopsis>
155
130
    <title>DESCRIPTION</title>
156
131
    <para>
157
132
      <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.
 
133
      be specified as <quote>keyscript</quote> in <citerefentry>
 
134
      <refentrytitle>crypttab</refentrytitle>
 
135
      <manvolnum>5</manvolnum></citerefentry> for the root disk.  The
 
136
      aim of this program is therefore to output a password, which
 
137
      then <citerefentry><refentrytitle>cryptsetup</refentrytitle>
 
138
      <manvolnum>8</manvolnum></citerefentry> will use to try and
 
139
      unlock the root disk.
165
140
    </para>
166
141
    <para>
167
142
      This program is not meant to be invoked directly, but can be in
185
160
    <variablelist>
186
161
      <varlistentry>
187
162
        <term><option>--global-env
188
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
163
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
189
164
        >value</replaceable></option></term>
190
 
        <term><option>-G
191
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
165
        <term><option>-e
 
166
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
192
167
        >value</replaceable></option></term>
193
168
        <listitem>
194
169
          <para>
204
179
        <replaceable>PLUGIN</replaceable><literal>:</literal
205
180
        ><replaceable>ENV</replaceable><literal>=</literal
206
181
        ><replaceable>value</replaceable></option></term>
207
 
        <term><option>-E
 
182
        <term><option>-f
208
183
        <replaceable>PLUGIN</replaceable><literal>:</literal
209
184
        ><replaceable>ENV</replaceable><literal>=</literal
210
185
        ><replaceable>value</replaceable></option></term>
230
205
            <replaceable>OPTIONS</replaceable> is a comma separated
231
206
            list of options.  This is not a very useful option, except
232
207
            for specifying the <quote><option>--debug</option></quote>
233
 
            option to all plugins.
 
208
            for all plugins.
234
209
          </para>
235
210
        </listitem>
236
211
      </varlistentry>
256
231
            <option>--bar</option> with the option argument
257
232
            <quote>baz</quote> is either
258
233
            <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.
 
234
            <userinput>--options-for=foo:--bar,baz</userinput>, but
 
235
            <emphasis>not</emphasis>
 
236
            <userinput>--options-for="foo:--bar baz"</userinput>.
262
237
          </para>
263
238
        </listitem>
264
239
      </varlistentry>
265
 
      
 
240
 
266
241
      <varlistentry>
267
 
        <term><option>--disable
 
242
        <term><option> --disable
268
243
        <replaceable>PLUGIN</replaceable></option></term>
269
244
        <term><option>-d
270
245
        <replaceable>PLUGIN</replaceable></option></term>
273
248
            Disable the plugin named
274
249
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
275
250
            started.
276
 
          </para>
277
 
        </listitem>
278
 
      </varlistentry>
279
 
      
280
 
      <varlistentry>
281
 
        <term><option>--enable
282
 
        <replaceable>PLUGIN</replaceable></option></term>
283
 
        <term><option>-e
284
 
        <replaceable>PLUGIN</replaceable></option></term>
285
 
        <listitem>
286
 
          <para>
287
 
            Re-enable the plugin named
288
 
            <replaceable>PLUGIN</replaceable>.  This is only useful to
289
 
            undo a previous <option>--disable</option> option, maybe
290
 
            from the configuration file.
291
 
          </para>
292
 
        </listitem>
293
 
      </varlistentry>
294
 
      
 
251
          </para>       
 
252
        </listitem>
 
253
      </varlistentry>
 
254
 
295
255
      <varlistentry>
296
256
        <term><option>--groupid
297
257
        <replaceable>ID</replaceable></option></term>
304
264
          </para>
305
265
        </listitem>
306
266
      </varlistentry>
307
 
      
 
267
 
308
268
      <varlistentry>
309
269
        <term><option>--userid
310
270
        <replaceable>ID</replaceable></option></term>
317
277
          </para>
318
278
        </listitem>
319
279
      </varlistentry>
320
 
      
 
280
 
321
281
      <varlistentry>
322
282
        <term><option>--plugin-dir
323
283
        <replaceable>DIRECTORY</replaceable></option></term>
332
292
      </varlistentry>
333
293
      
334
294
      <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
 
        <term><option>--config-file
351
 
        <replaceable>FILE</replaceable></option></term>
352
 
        <listitem>
353
 
          <para>
354
 
            Specify a different file to read additional options from.
355
 
            See <xref linkend="files"/>.  Other command line options
356
 
            will override options specified in the file.
357
 
          </para>
358
 
        </listitem>
359
 
      </varlistentry>
360
 
      
361
 
      <varlistentry>
362
295
        <term><option>--debug</option></term>
363
296
        <listitem>
364
297
          <para>
395
328
          </para>
396
329
        </listitem>
397
330
      </varlistentry>
398
 
      
 
331
 
399
332
      <varlistentry>
400
333
        <term><option>--version</option></term>
401
334
        <term><option>-V</option></term>
407
340
      </varlistentry>
408
341
    </variablelist>
409
342
  </refsect1>
410
 
  
 
343
 
411
344
  <refsect1 id="overview">
412
345
    <title>OVERVIEW</title>
413
346
    <xi:include href="overview.xml"/>
433
366
      code will make this plugin-runner output the password from that
434
367
      plugin, stop any other plugins, and exit.
435
368
    </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
369
  </refsect1>
479
370
  
480
371
  <refsect1 id="fallback">
502
393
  <refsect1 id="environment">
503
394
    <title>ENVIRONMENT</title>
504
395
    <para>
505
 
      This program does not use any environment variables itself, it
506
 
      only passes on its environment to all the plugins.  The
507
 
      environment passed to plugins can be modified using the
508
 
      <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.
 
396
      
512
397
    </para>
513
398
  </refsect1>
514
399
  
515
 
  <refsect1 id="files">
 
400
  <refsect1 id="file">
516
401
    <title>FILES</title>
517
402
    <para>
518
403
      <variablelist>
530
415
              of a line is ignored.
531
416
            </para>
532
417
            <para>
533
 
              This program is meant to run in the initial RAM disk
534
 
              environment, so that is where this file is assumed to
535
 
              exist.  The file does not need to exist in the normal
536
 
              file system.
537
 
            </para>
538
 
            <para>
539
418
              This file will be processed <emphasis>before</emphasis>
540
419
              the normal command line options, so the latter can
541
420
              override the former, if need be.
542
421
            </para>
543
 
            <para>
544
 
              This file name is the default; the file to read for
545
 
              arguments can be changed using the
546
 
              <option>--config-file</option> option.
547
 
            </para>
548
 
          </listitem>
549
 
        </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
422
          </listitem>
569
423
        </varlistentry>
570
424
      </variablelist>
574
428
  <refsect1 id="bugs">
575
429
    <title>BUGS</title>
576
430
    <para>
577
 
      The <option>--config-file</option> option is ignored when
578
 
      specified from within a configuration file.
 
431
      There is no <option>--enable</option> option to enable disabled
 
432
      plugins.
579
433
    </para>
580
 
    <xi:include href="bugs.xml"/>
581
434
  </refsect1>
582
435
  
583
436
  <refsect1 id="examples">
584
437
    <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 four 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,&#x200b;--seckey=seckey.txt,&#x200b;--tls-pubkey=tls-pubkey.pem,&#x200b;--tls-privkey=tls-privkey.pem</userinput>
639
 
 
640
 
      </para>
641
 
    </informalexample>
 
438
    <para>
 
439
    </para>
642
440
  </refsect1>
 
441
  
643
442
  <refsect1 id="security">
644
443
    <title>SECURITY</title>
645
444
    <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
445
    </para>
671
446
  </refsect1>
672
447
  
673
448
  <refsect1 id="see_also">
674
449
    <title>SEE ALSO</title>
675
450
    <para>
676
 
      <citerefentry><refentrytitle>intro</refentrytitle>
677
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
678
451
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
679
452
      <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
453
      <citerefentry><refentrytitle>mandos</refentrytitle>
685
454
      <manvolnum>8</manvolnum></citerefentry>,
686
455
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
687
456
      <manvolnum>8mandos</manvolnum></citerefentry>,
688
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
457
      <citerefentry><refentrytitle>password-request</refentrytitle>
689
458
      <manvolnum>8mandos</manvolnum></citerefentry>
690
459
    </para>
691
460
  </refsect1>