/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 "2015-07-20">
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
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
 
        <arg choice="plain"><option>-G
68
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
59
        <arg choice="plain"><option>-e
 
60
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
69
61
        >value</replaceable> </option></arg>
70
62
      </group>
71
63
      <sbr/>
74
66
        >PLUGIN</replaceable><literal>:</literal><replaceable
75
67
        >ENV</replaceable><literal>=</literal><replaceable
76
68
        >value</replaceable></option></arg>
77
 
        <arg choice="plain"><option>-E<replaceable>
 
69
        <arg choice="plain"><option>-f<replaceable>
78
70
        PLUGIN</replaceable><literal>:</literal><replaceable
79
71
        >ENV</replaceable><literal>=</literal><replaceable
80
72
        >value</replaceable> </option></arg>
91
83
        <arg choice="plain"><option>--options-for=<replaceable
92
84
        >PLUGIN</replaceable><literal>:</literal><replaceable
93
85
        >OPTIONS</replaceable></option></arg>
94
 
        <arg choice="plain"><option>-o<replaceable>
 
86
        <arg choice="plain"><option>-f<replaceable>
95
87
        PLUGIN</replaceable><literal>:</literal><replaceable
96
88
        >OPTIONS</replaceable> </option></arg>
97
89
      </group>
103
95
        <replaceable>PLUGIN</replaceable> </option></arg>
104
96
      </group>
105
97
      <sbr/>
106
 
      <group rep="repeat">
107
 
        <arg choice="plain"><option>--enable=<replaceable
108
 
        >PLUGIN</replaceable></option></arg>
109
 
        <arg choice="plain"><option>-e
110
 
        <replaceable>PLUGIN</replaceable> </option></arg>
111
 
      </group>
112
 
      <sbr/>
113
98
      <arg><option>--groupid=<replaceable
114
99
      >ID</replaceable></option></arg>
115
100
      <sbr/>
119
104
      <arg><option>--plugin-dir=<replaceable
120
105
      >DIRECTORY</replaceable></option></arg>
121
106
      <sbr/>
122
 
      <arg><option>--plugin-helper-dir=<replaceable
123
 
      >DIRECTORY</replaceable></option></arg>
124
 
      <sbr/>
125
 
      <arg><option>--config-file=<replaceable
126
 
      >FILE</replaceable></option></arg>
127
 
      <sbr/>
128
107
      <arg><option>--debug</option></arg>
129
108
    </cmdsynopsis>
130
109
    <cmdsynopsis>
151
130
    <title>DESCRIPTION</title>
152
131
    <para>
153
132
      <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>
159
 
      <manvolnum>8</manvolnum></citerefentry> will use to unlock the
160
 
      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.
161
140
    </para>
162
141
    <para>
163
142
      This program is not meant to be invoked directly, but can be in
181
160
    <variablelist>
182
161
      <varlistentry>
183
162
        <term><option>--global-env
184
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
163
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
185
164
        >value</replaceable></option></term>
186
 
        <term><option>-G
187
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
165
        <term><option>-e
 
166
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
188
167
        >value</replaceable></option></term>
189
168
        <listitem>
190
169
          <para>
200
179
        <replaceable>PLUGIN</replaceable><literal>:</literal
201
180
        ><replaceable>ENV</replaceable><literal>=</literal
202
181
        ><replaceable>value</replaceable></option></term>
203
 
        <term><option>-E
 
182
        <term><option>-f
204
183
        <replaceable>PLUGIN</replaceable><literal>:</literal
205
184
        ><replaceable>ENV</replaceable><literal>=</literal
206
185
        ><replaceable>value</replaceable></option></term>
226
205
            <replaceable>OPTIONS</replaceable> is a comma separated
227
206
            list of options.  This is not a very useful option, except
228
207
            for specifying the <quote><option>--debug</option></quote>
229
 
            option to all plugins.
 
208
            for all plugins.
230
209
          </para>
231
210
        </listitem>
232
211
      </varlistentry>
252
231
            <option>--bar</option> with the option argument
253
232
            <quote>baz</quote> is either
254
233
            <userinput>--options-for=foo:--bar=baz</userinput> or
255
 
            <userinput>--options-for=foo:--bar,baz</userinput>.  Using
256
 
            <userinput>--options-for="foo:--bar baz"</userinput>. will
257
 
            <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>.
258
237
          </para>
259
238
        </listitem>
260
239
      </varlistentry>
261
 
      
 
240
 
262
241
      <varlistentry>
263
 
        <term><option>--disable
 
242
        <term><option> --disable
264
243
        <replaceable>PLUGIN</replaceable></option></term>
265
244
        <term><option>-d
266
245
        <replaceable>PLUGIN</replaceable></option></term>
269
248
            Disable the plugin named
270
249
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
271
250
            started.
272
 
          </para>
273
 
        </listitem>
274
 
      </varlistentry>
275
 
      
276
 
      <varlistentry>
277
 
        <term><option>--enable
278
 
        <replaceable>PLUGIN</replaceable></option></term>
279
 
        <term><option>-e
280
 
        <replaceable>PLUGIN</replaceable></option></term>
281
 
        <listitem>
282
 
          <para>
283
 
            Re-enable the plugin named
284
 
            <replaceable>PLUGIN</replaceable>.  This is only useful to
285
 
            undo a previous <option>--disable</option> option, maybe
286
 
            from the configuration file.
287
 
          </para>
288
 
        </listitem>
289
 
      </varlistentry>
290
 
      
 
251
          </para>       
 
252
        </listitem>
 
253
      </varlistentry>
 
254
 
291
255
      <varlistentry>
292
256
        <term><option>--groupid
293
257
        <replaceable>ID</replaceable></option></term>
300
264
          </para>
301
265
        </listitem>
302
266
      </varlistentry>
303
 
      
 
267
 
304
268
      <varlistentry>
305
269
        <term><option>--userid
306
270
        <replaceable>ID</replaceable></option></term>
313
277
          </para>
314
278
        </listitem>
315
279
      </varlistentry>
316
 
      
 
280
 
317
281
      <varlistentry>
318
282
        <term><option>--plugin-dir
319
283
        <replaceable>DIRECTORY</replaceable></option></term>
328
292
      </varlistentry>
329
293
      
330
294
      <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
 
        <term><option>--config-file
347
 
        <replaceable>FILE</replaceable></option></term>
348
 
        <listitem>
349
 
          <para>
350
 
            Specify a different file to read additional options from.
351
 
            See <xref linkend="files"/>.  Other command line options
352
 
            will override options specified in the file.
353
 
          </para>
354
 
        </listitem>
355
 
      </varlistentry>
356
 
      
357
 
      <varlistentry>
358
295
        <term><option>--debug</option></term>
359
296
        <listitem>
360
297
          <para>
391
328
          </para>
392
329
        </listitem>
393
330
      </varlistentry>
394
 
      
 
331
 
395
332
      <varlistentry>
396
333
        <term><option>--version</option></term>
397
334
        <term><option>-V</option></term>
403
340
      </varlistentry>
404
341
    </variablelist>
405
342
  </refsect1>
406
 
  
 
343
 
407
344
  <refsect1 id="overview">
408
345
    <title>OVERVIEW</title>
409
346
    <xi:include href="overview.xml"/>
429
366
      code will make this plugin-runner output the password from that
430
367
      plugin, stop any other plugins, and exit.
431
368
    </para>
432
 
    
433
 
    <refsect2 id="writing_plugins">
434
 
      <title>WRITING PLUGINS</title>
435
 
      <para>
436
 
        A plugin is simply a program which prints a password to its
437
 
        standard output and then exits with a successful (zero) exit
438
 
        status.  If the exit status is not zero, any output on
439
 
        standard output will be ignored by the plugin runner.  Any
440
 
        output on its standard error channel will simply be passed to
441
 
        the standard error of the plugin runner, usually the system
442
 
        console.
443
 
      </para>
444
 
      <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
 
        The plugin will run in the initial RAM disk environment, so
451
 
        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.
457
 
      </para>
458
 
      <para>
459
 
        The plugin must exit cleanly and free all allocated resources
460
 
        upon getting the TERM signal, since this is what the plugin
461
 
        runner uses to stop all other plugins when one plugin has
462
 
        output a password and exited cleanly.
463
 
      </para>
464
 
      <para>
465
 
        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.
468
 
      </para>
469
 
      <para>
470
 
        It is useful, but not required, for the plugin to take the
471
 
        <option>--debug</option> option.
472
 
      </para>
473
 
    </refsect2>
474
369
  </refsect1>
475
370
  
476
371
  <refsect1 id="fallback">
498
393
  <refsect1 id="environment">
499
394
    <title>ENVIRONMENT</title>
500
395
    <para>
501
 
      This program does not use any environment variables itself, it
502
 
      only passes on its environment to all the plugins.  The
503
 
      environment passed to plugins can be modified using the
504
 
      <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.
 
396
      
508
397
    </para>
509
398
  </refsect1>
510
399
  
511
 
  <refsect1 id="files">
 
400
  <refsect1 id="file">
512
401
    <title>FILES</title>
513
402
    <para>
514
403
      <variablelist>
526
415
              of a line is ignored.
527
416
            </para>
528
417
            <para>
529
 
              This program is meant to run in the initial RAM disk
530
 
              environment, so that is where this file is assumed to
531
 
              exist.  The file does not need to exist in the normal
532
 
              file system.
533
 
            </para>
534
 
            <para>
535
418
              This file will be processed <emphasis>before</emphasis>
536
419
              the normal command line options, so the latter can
537
420
              override the former, if need be.
538
421
            </para>
539
 
            <para>
540
 
              This file name is the default; the file to read for
541
 
              arguments can be changed using the
542
 
              <option>--config-file</option> option.
543
 
            </para>
544
422
          </listitem>
545
423
        </varlistentry>
546
424
      </variablelist>
550
428
  <refsect1 id="bugs">
551
429
    <title>BUGS</title>
552
430
    <para>
553
 
      The <option>--config-file</option> option is ignored when
554
 
      specified from within a configuration file.
 
431
      There is no <option>--enable</option> option to enable disabled
 
432
      plugins.
555
433
    </para>
556
434
  </refsect1>
557
435
  
558
436
  <refsect1 id="examples">
559
437
    <title>EXAMPLE</title>
560
 
    <informalexample>
561
 
      <para>
562
 
        Normal invocation needs no options:
563
 
      </para>
564
 
      <para>
565
 
        <userinput>&COMMANDNAME;</userinput>
566
 
      </para>
567
 
    </informalexample>
568
 
    <informalexample>
569
 
      <para>
570
 
        Run the program, but not the plugins, in debug mode:
571
 
      </para>
572
 
      <para>
573
 
        
574
 
        <!-- do not wrap this line -->
575
 
        <userinput>&COMMANDNAME; --debug</userinput>
576
 
        
577
 
      </para>
578
 
    </informalexample>
579
 
    <informalexample>
580
 
      <para>
581
 
        Run all plugins, but run the <quote>foo</quote> plugin in
582
 
        debug mode:
583
 
      </para>
584
 
      <para>
585
 
        
586
 
        <!-- do not wrap this line -->
587
 
        <userinput>&COMMANDNAME; --options-for=foo:--debug</userinput>
588
 
        
589
 
      </para>
590
 
    </informalexample>
591
 
    <informalexample>
592
 
      <para>
593
 
        Run all plugins, but not the program, in debug mode:
594
 
      </para>
595
 
      <para>
596
 
        
597
 
        <!-- do not wrap this line -->
598
 
        <userinput>&COMMANDNAME; --global-options=--debug</userinput>
599
 
        
600
 
      </para>
601
 
    </informalexample>
602
 
    <informalexample>
603
 
      <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>
608
 
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
609
 
      </para>
610
 
      <para>
611
 
 
612
 
<!-- 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>
614
 
 
615
 
      </para>
616
 
    </informalexample>
 
438
    <para>
 
439
    </para>
617
440
  </refsect1>
 
441
  
618
442
  <refsect1 id="security">
619
443
    <title>SECURITY</title>
620
444
    <para>
621
 
      This program will, when starting, try to switch to another user.
622
 
      If it is started as root, it will succeed, and will by default
623
 
      switch to user and group 65534, which are assumed to be
624
 
      non-privileged.  This user and group is then what all plugins
625
 
      will be started as.  Therefore, the only way to run a plugin as
626
 
      a privileged user is to have the set-user-ID or set-group-ID bit
627
 
      set on the plugin executable file (see <citerefentry>
628
 
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
629
 
      </citerefentry>).
630
 
    </para>
631
 
    <para>
632
 
      If this program is used as a keyscript in <citerefentry
633
 
      ><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
637
 
      image to not run this program.  This is, however, unlikely,
638
 
      since the <citerefentry><refentrytitle
639
 
      >password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
640
 
      </citerefentry> plugin will read a password from the console in
641
 
      case of failure of the other plugins, and this plugin runner
642
 
      will also, in case of catastrophic failure, itself fall back to
643
 
      asking and outputting a password on the console (see <xref
644
 
      linkend="fallback"/>).
645
445
    </para>
646
446
  </refsect1>
647
447
  
648
448
  <refsect1 id="see_also">
649
449
    <title>SEE ALSO</title>
650
450
    <para>
651
 
      <citerefentry><refentrytitle>intro</refentrytitle>
652
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
653
451
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
654
452
      <manvolnum>8</manvolnum></citerefentry>,
655
 
      <citerefentry><refentrytitle>crypttab</refentrytitle>
656
 
      <manvolnum>5</manvolnum></citerefentry>,
657
 
      <citerefentry><refentrytitle>execve</refentrytitle>
658
 
      <manvolnum>2</manvolnum></citerefentry>,
659
453
      <citerefentry><refentrytitle>mandos</refentrytitle>
660
454
      <manvolnum>8</manvolnum></citerefentry>,
661
455
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
662
456
      <manvolnum>8mandos</manvolnum></citerefentry>,
663
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
457
      <citerefentry><refentrytitle>password-request</refentrytitle>
664
458
      <manvolnum>8mandos</manvolnum></citerefentry>
665
459
    </para>
666
460
  </refsect1>