/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:19:32 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080901161932-ostp7tulh9aijulh
* plugin-runner.c (add_environment): Never insert existing environment
                                     variables.
  (main): Rename "--global-envs" to "--global-env" and "--envs-for" to
          "--env-for".

* plugin-runner.xml (SYNOPSIS): Rename "--global-envs" to
                                "--global-env" and "--envs-for" to
                                "--env-for".
  (OPTIONS): Added "--global-env" and "--env-for".
  (FALLBACK): Add id attribute.
  (EXIT STATUS): Add text.
  (ENVIRONMENT): New section.
  (FILES): Document configuration file.

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>
191
 
            This option will add an environment variable setting to
192
 
            all plugins.  This will override any inherited environment
193
 
            variable.
 
170
            
194
171
          </para>
195
172
        </listitem>
196
173
      </varlistentry>
200
177
        <replaceable>PLUGIN</replaceable><literal>:</literal
201
178
        ><replaceable>ENV</replaceable><literal>=</literal
202
179
        ><replaceable>value</replaceable></option></term>
203
 
        <term><option>-E
 
180
        <term><option>-f
204
181
        <replaceable>PLUGIN</replaceable><literal>:</literal
205
182
        ><replaceable>ENV</replaceable><literal>=</literal
206
183
        ><replaceable>value</replaceable></option></term>
207
184
        <listitem>
208
185
          <para>
209
 
            This option will add an environment variable setting to
210
 
            the <replaceable>PLUGIN</replaceable> plugin.  This will
211
 
            override any inherited environment variables or
212
 
            environment variables specified using
213
 
            <option>--global-env</option>.
214
186
          </para>
215
187
        </listitem>
216
188
      </varlistentry>
226
198
            <replaceable>OPTIONS</replaceable> is a comma separated
227
199
            list of options.  This is not a very useful option, except
228
200
            for specifying the <quote><option>--debug</option></quote>
229
 
            option to all plugins.
 
201
            for all plugins.
230
202
          </para>
231
203
        </listitem>
232
204
      </varlistentry>
252
224
            <option>--bar</option> with the option argument
253
225
            <quote>baz</quote> is either
254
226
            <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.
 
227
            <userinput>--options-for=foo:--bar,baz</userinput>, but
 
228
            <emphasis>not</emphasis>
 
229
            <userinput>--options-for="foo:--bar baz"</userinput>.
258
230
          </para>
259
231
        </listitem>
260
232
      </varlistentry>
261
 
      
 
233
 
262
234
      <varlistentry>
263
 
        <term><option>--disable
 
235
        <term><option> --disable
264
236
        <replaceable>PLUGIN</replaceable></option></term>
265
237
        <term><option>-d
266
238
        <replaceable>PLUGIN</replaceable></option></term>
269
241
            Disable the plugin named
270
242
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
271
243
            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
 
      
 
244
          </para>       
 
245
        </listitem>
 
246
      </varlistentry>
 
247
 
291
248
      <varlistentry>
292
249
        <term><option>--groupid
293
250
        <replaceable>ID</replaceable></option></term>
300
257
          </para>
301
258
        </listitem>
302
259
      </varlistentry>
303
 
      
 
260
 
304
261
      <varlistentry>
305
262
        <term><option>--userid
306
263
        <replaceable>ID</replaceable></option></term>
313
270
          </para>
314
271
        </listitem>
315
272
      </varlistentry>
316
 
      
 
273
 
317
274
      <varlistentry>
318
275
        <term><option>--plugin-dir
319
276
        <replaceable>DIRECTORY</replaceable></option></term>
328
285
      </varlistentry>
329
286
      
330
287
      <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
288
        <term><option>--debug</option></term>
359
289
        <listitem>
360
290
          <para>
391
321
          </para>
392
322
        </listitem>
393
323
      </varlistentry>
394
 
      
 
324
 
395
325
      <varlistentry>
396
326
        <term><option>--version</option></term>
397
327
        <term><option>-V</option></term>
403
333
      </varlistentry>
404
334
    </variablelist>
405
335
  </refsect1>
406
 
  
 
336
 
407
337
  <refsect1 id="overview">
408
338
    <title>OVERVIEW</title>
409
339
    <xi:include href="overview.xml"/>
429
359
      code will make this plugin-runner output the password from that
430
360
      plugin, stop any other plugins, and exit.
431
361
    </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
362
  </refsect1>
475
363
  
476
364
  <refsect1 id="fallback">
498
386
  <refsect1 id="environment">
499
387
    <title>ENVIRONMENT</title>
500
388
    <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.
 
389
      
508
390
    </para>
509
391
  </refsect1>
510
392
  
511
 
  <refsect1 id="files">
 
393
  <refsect1 id="file">
512
394
    <title>FILES</title>
513
395
    <para>
514
396
      <variablelist>
525
407
              everything from a <quote>#</quote> character to the end
526
408
              of a line is ignored.
527
409
            </para>
528
 
            <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
 
              This file will be processed <emphasis>before</emphasis>
536
 
              the normal command line options, so the latter can
537
 
              override the former, if need be.
538
 
            </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
410
          </listitem>
545
411
        </varlistentry>
546
412
      </variablelist>
550
416
  <refsect1 id="bugs">
551
417
    <title>BUGS</title>
552
418
    <para>
553
 
      The <option>--config-file</option> option is ignored when
554
 
      specified from within a configuration file.
555
419
    </para>
556
420
  </refsect1>
557
421
  
558
422
  <refsect1 id="examples">
559
423
    <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>
 
424
    <para>
 
425
    </para>
617
426
  </refsect1>
 
427
  
618
428
  <refsect1 id="security">
619
429
    <title>SECURITY</title>
620
430
    <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
431
    </para>
646
432
  </refsect1>
647
433
  
648
434
  <refsect1 id="see_also">
649
435
    <title>SEE ALSO</title>
650
436
    <para>
651
 
      <citerefentry><refentrytitle>intro</refentrytitle>
652
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
653
437
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
654
438
      <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
439
      <citerefentry><refentrytitle>mandos</refentrytitle>
660
440
      <manvolnum>8</manvolnum></citerefentry>,
661
441
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
662
442
      <manvolnum>8mandos</manvolnum></citerefentry>,
663
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
443
      <citerefentry><refentrytitle>password-request</refentrytitle>
664
444
      <manvolnum>8mandos</manvolnum></citerefentry>
665
445
    </para>
666
446
  </refsect1>