/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 06:13:47 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080902061347-psw61eqt17j425sq
* plugin-runner.c: Changed short option for "--global-env" to "-G",
                   changed short option for "--env-for" to "-E",
                   added new option "--enable" ("-e").

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 "2015-06-28">
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>2012</year>
37
34
      <holder>Teddy Hogeborn</holder>
38
35
      <holder>Björn Påhlsson</holder>
39
36
    </copyright>
40
37
    <xi:include href="legalnotice.xml"/>
41
38
  </refentryinfo>
42
 
  
 
39
 
43
40
  <refmeta>
44
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
45
42
    <manvolnum>8mandos</manvolnum>
48
45
  <refnamediv>
49
46
    <refname><command>&COMMANDNAME;</command></refname>
50
47
    <refpurpose>
51
 
      Run Mandos plugins, pass data from first to succeed.
 
48
      Run Mandos plugins.  Pass data from first succesful one.
52
49
    </refpurpose>
53
50
  </refnamediv>
54
 
  
 
51
 
55
52
  <refsynopsisdiv>
56
53
    <cmdsynopsis>
57
54
      <command>&COMMANDNAME;</command>
58
55
      <group rep="repeat">
59
56
        <arg choice="plain"><option>--global-env=<replaceable
60
 
        >ENV</replaceable><literal>=</literal><replaceable
 
57
        >VAR</replaceable><literal>=</literal><replaceable
61
58
        >value</replaceable></option></arg>
62
 
        <arg choice="plain"><option>-G
63
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
59
        <arg choice="plain"><option>-e
 
60
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
64
61
        >value</replaceable> </option></arg>
65
62
      </group>
66
63
      <sbr/>
69
66
        >PLUGIN</replaceable><literal>:</literal><replaceable
70
67
        >ENV</replaceable><literal>=</literal><replaceable
71
68
        >value</replaceable></option></arg>
72
 
        <arg choice="plain"><option>-E<replaceable>
 
69
        <arg choice="plain"><option>-f<replaceable>
73
70
        PLUGIN</replaceable><literal>:</literal><replaceable
74
71
        >ENV</replaceable><literal>=</literal><replaceable
75
72
        >value</replaceable> </option></arg>
86
83
        <arg choice="plain"><option>--options-for=<replaceable
87
84
        >PLUGIN</replaceable><literal>:</literal><replaceable
88
85
        >OPTIONS</replaceable></option></arg>
89
 
        <arg choice="plain"><option>-o<replaceable>
 
86
        <arg choice="plain"><option>-f<replaceable>
90
87
        PLUGIN</replaceable><literal>:</literal><replaceable
91
88
        >OPTIONS</replaceable> </option></arg>
92
89
      </group>
98
95
        <replaceable>PLUGIN</replaceable> </option></arg>
99
96
      </group>
100
97
      <sbr/>
101
 
      <group rep="repeat">
102
 
        <arg choice="plain"><option>--enable=<replaceable
103
 
        >PLUGIN</replaceable></option></arg>
104
 
        <arg choice="plain"><option>-e
105
 
        <replaceable>PLUGIN</replaceable> </option></arg>
106
 
      </group>
107
 
      <sbr/>
108
98
      <arg><option>--groupid=<replaceable
109
99
      >ID</replaceable></option></arg>
110
100
      <sbr/>
114
104
      <arg><option>--plugin-dir=<replaceable
115
105
      >DIRECTORY</replaceable></option></arg>
116
106
      <sbr/>
117
 
      <arg><option>--plugin-helper-dir=<replaceable
118
 
      >DIRECTORY</replaceable></option></arg>
119
 
      <sbr/>
120
 
      <arg><option>--config-file=<replaceable
121
 
      >FILE</replaceable></option></arg>
122
 
      <sbr/>
123
107
      <arg><option>--debug</option></arg>
124
108
    </cmdsynopsis>
125
109
    <cmdsynopsis>
146
130
    <title>DESCRIPTION</title>
147
131
    <para>
148
132
      <command>&COMMANDNAME;</command> is a program which is meant to
149
 
      be specified as a <quote>keyscript</quote> for the root disk in
150
 
      <citerefentry><refentrytitle>crypttab</refentrytitle>
151
 
      <manvolnum>5</manvolnum></citerefentry>.  The aim of this
152
 
      program is therefore to output a password, which then
153
 
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
154
 
      <manvolnum>8</manvolnum></citerefentry> will use to unlock the
155
 
      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.
156
140
    </para>
157
141
    <para>
158
142
      This program is not meant to be invoked directly, but can be in
176
160
    <variablelist>
177
161
      <varlistentry>
178
162
        <term><option>--global-env
179
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
163
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
180
164
        >value</replaceable></option></term>
181
 
        <term><option>-G
182
 
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
 
165
        <term><option>-e
 
166
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
183
167
        >value</replaceable></option></term>
184
168
        <listitem>
185
169
          <para>
195
179
        <replaceable>PLUGIN</replaceable><literal>:</literal
196
180
        ><replaceable>ENV</replaceable><literal>=</literal
197
181
        ><replaceable>value</replaceable></option></term>
198
 
        <term><option>-E
 
182
        <term><option>-f
199
183
        <replaceable>PLUGIN</replaceable><literal>:</literal
200
184
        ><replaceable>ENV</replaceable><literal>=</literal
201
185
        ><replaceable>value</replaceable></option></term>
221
205
            <replaceable>OPTIONS</replaceable> is a comma separated
222
206
            list of options.  This is not a very useful option, except
223
207
            for specifying the <quote><option>--debug</option></quote>
224
 
            option to all plugins.
 
208
            for all plugins.
225
209
          </para>
226
210
        </listitem>
227
211
      </varlistentry>
247
231
            <option>--bar</option> with the option argument
248
232
            <quote>baz</quote> is either
249
233
            <userinput>--options-for=foo:--bar=baz</userinput> or
250
 
            <userinput>--options-for=foo:--bar,baz</userinput>.  Using
251
 
            <userinput>--options-for="foo:--bar baz"</userinput>. will
252
 
            <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>.
253
237
          </para>
254
238
        </listitem>
255
239
      </varlistentry>
256
 
      
 
240
 
257
241
      <varlistentry>
258
 
        <term><option>--disable
 
242
        <term><option> --disable
259
243
        <replaceable>PLUGIN</replaceable></option></term>
260
244
        <term><option>-d
261
245
        <replaceable>PLUGIN</replaceable></option></term>
264
248
            Disable the plugin named
265
249
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
266
250
            started.
267
 
          </para>
268
 
        </listitem>
269
 
      </varlistentry>
270
 
      
271
 
      <varlistentry>
272
 
        <term><option>--enable
273
 
        <replaceable>PLUGIN</replaceable></option></term>
274
 
        <term><option>-e
275
 
        <replaceable>PLUGIN</replaceable></option></term>
276
 
        <listitem>
277
 
          <para>
278
 
            Re-enable the plugin named
279
 
            <replaceable>PLUGIN</replaceable>.  This is only useful to
280
 
            undo a previous <option>--disable</option> option, maybe
281
 
            from the configuration file.
282
 
          </para>
283
 
        </listitem>
284
 
      </varlistentry>
285
 
      
 
251
          </para>       
 
252
        </listitem>
 
253
      </varlistentry>
 
254
 
286
255
      <varlistentry>
287
256
        <term><option>--groupid
288
257
        <replaceable>ID</replaceable></option></term>
295
264
          </para>
296
265
        </listitem>
297
266
      </varlistentry>
298
 
      
 
267
 
299
268
      <varlistentry>
300
269
        <term><option>--userid
301
270
        <replaceable>ID</replaceable></option></term>
308
277
          </para>
309
278
        </listitem>
310
279
      </varlistentry>
311
 
      
 
280
 
312
281
      <varlistentry>
313
282
        <term><option>--plugin-dir
314
283
        <replaceable>DIRECTORY</replaceable></option></term>
323
292
      </varlistentry>
324
293
      
325
294
      <varlistentry>
326
 
        <term><option>--plugin-helper-dir
327
 
        <replaceable>DIRECTORY</replaceable></option></term>
328
 
        <listitem>
329
 
          <para>
330
 
            Specify a different plugin helper directory.  The default
331
 
            is <filename>/lib/mandos/plugin-helpers</filename>, which
332
 
            will exist in the initial <acronym>RAM</acronym> disk
333
 
            environment.  (This will simply be passed to all plugins
334
 
            via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
335
 
            variable.  See <xref linkend="writing_plugins"/>)
336
 
          </para>
337
 
        </listitem>
338
 
      </varlistentry>
339
 
      
340
 
      <varlistentry>
341
 
        <term><option>--config-file
342
 
        <replaceable>FILE</replaceable></option></term>
343
 
        <listitem>
344
 
          <para>
345
 
            Specify a different file to read additional options from.
346
 
            See <xref linkend="files"/>.  Other command line options
347
 
            will override options specified in the file.
348
 
          </para>
349
 
        </listitem>
350
 
      </varlistentry>
351
 
      
352
 
      <varlistentry>
353
295
        <term><option>--debug</option></term>
354
296
        <listitem>
355
297
          <para>
386
328
          </para>
387
329
        </listitem>
388
330
      </varlistentry>
389
 
      
 
331
 
390
332
      <varlistentry>
391
333
        <term><option>--version</option></term>
392
334
        <term><option>-V</option></term>
398
340
      </varlistentry>
399
341
    </variablelist>
400
342
  </refsect1>
401
 
  
 
343
 
402
344
  <refsect1 id="overview">
403
345
    <title>OVERVIEW</title>
404
346
    <xi:include href="overview.xml"/>
424
366
      code will make this plugin-runner output the password from that
425
367
      plugin, stop any other plugins, and exit.
426
368
    </para>
427
 
    
428
 
    <refsect2 id="writing_plugins">
429
 
      <title>WRITING PLUGINS</title>
430
 
      <para>
431
 
        A plugin is simply a program which prints a password to its
432
 
        standard output and then exits with a successful (zero) exit
433
 
        status.  If the exit status is not zero, any output on
434
 
        standard output will be ignored by the plugin runner.  Any
435
 
        output on its standard error channel will simply be passed to
436
 
        the standard error of the plugin runner, usually the system
437
 
        console.
438
 
      </para>
439
 
      <para>
440
 
        If the password is a single-line, manually entered passprase,
441
 
        a final trailing newline character should
442
 
        <emphasis>not</emphasis> be printed.
443
 
      </para>
444
 
      <para>
445
 
        The plugin will run in the initial RAM disk environment, so
446
 
        care must be taken not to depend on any files or running
447
 
        services not available there.  Any helper executables required
448
 
        by the plugin (which are not in the <envar>PATH</envar>) can
449
 
        be placed in the plugin helper directory, the name of which
450
 
        will be made available to the plugin via the
451
 
        <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
452
 
      </para>
453
 
      <para>
454
 
        The plugin must exit cleanly and free all allocated resources
455
 
        upon getting the TERM signal, since this is what the plugin
456
 
        runner uses to stop all other plugins when one plugin has
457
 
        output a password and exited cleanly.
458
 
      </para>
459
 
      <para>
460
 
        The plugin must not use resources, like for instance reading
461
 
        from the standard input, without knowing that no other plugin
462
 
        is also using it.
463
 
      </para>
464
 
      <para>
465
 
        It is useful, but not required, for the plugin to take the
466
 
        <option>--debug</option> option.
467
 
      </para>
468
 
    </refsect2>
469
369
  </refsect1>
470
370
  
471
371
  <refsect1 id="fallback">
493
393
  <refsect1 id="environment">
494
394
    <title>ENVIRONMENT</title>
495
395
    <para>
496
 
      This program does not use any environment variables itself, it
497
 
      only passes on its environment to all the plugins.  The
498
 
      environment passed to plugins can be modified using the
499
 
      <option>--global-env</option> and <option>--env-for</option>
500
 
      options.  Also, the <option>--plugin-helper-dir</option> option
501
 
      will affect the environment variable
502
 
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
 
396
      
503
397
    </para>
504
398
  </refsect1>
505
399
  
506
 
  <refsect1 id="files">
 
400
  <refsect1 id="file">
507
401
    <title>FILES</title>
508
402
    <para>
509
403
      <variablelist>
521
415
              of a line is ignored.
522
416
            </para>
523
417
            <para>
524
 
              This program is meant to run in the initial RAM disk
525
 
              environment, so that is where this file is assumed to
526
 
              exist.  The file does not need to exist in the normal
527
 
              file system.
528
 
            </para>
529
 
            <para>
530
418
              This file will be processed <emphasis>before</emphasis>
531
419
              the normal command line options, so the latter can
532
420
              override the former, if need be.
533
421
            </para>
534
 
            <para>
535
 
              This file name is the default; the file to read for
536
 
              arguments can be changed using the
537
 
              <option>--config-file</option> option.
538
 
            </para>
539
422
          </listitem>
540
423
        </varlistentry>
541
424
      </variablelist>
545
428
  <refsect1 id="bugs">
546
429
    <title>BUGS</title>
547
430
    <para>
548
 
      The <option>--config-file</option> option is ignored when
549
 
      specified from within a configuration file.
 
431
      There is no <option>--enable</option> option to enable disabled
 
432
      plugins.
550
433
    </para>
551
434
  </refsect1>
552
435
  
553
436
  <refsect1 id="examples">
554
437
    <title>EXAMPLE</title>
555
 
    <informalexample>
556
 
      <para>
557
 
        Normal invocation needs no options:
558
 
      </para>
559
 
      <para>
560
 
        <userinput>&COMMANDNAME;</userinput>
561
 
      </para>
562
 
    </informalexample>
563
 
    <informalexample>
564
 
      <para>
565
 
        Run the program, but not the plugins, in debug mode:
566
 
      </para>
567
 
      <para>
568
 
        
569
 
        <!-- do not wrap this line -->
570
 
        <userinput>&COMMANDNAME; --debug</userinput>
571
 
        
572
 
      </para>
573
 
    </informalexample>
574
 
    <informalexample>
575
 
      <para>
576
 
        Run all plugins, but run the <quote>foo</quote> plugin in
577
 
        debug mode:
578
 
      </para>
579
 
      <para>
580
 
        
581
 
        <!-- do not wrap this line -->
582
 
        <userinput>&COMMANDNAME; --options-for=foo:--debug</userinput>
583
 
        
584
 
      </para>
585
 
    </informalexample>
586
 
    <informalexample>
587
 
      <para>
588
 
        Run all plugins, but not the program, in debug mode:
589
 
      </para>
590
 
      <para>
591
 
        
592
 
        <!-- do not wrap this line -->
593
 
        <userinput>&COMMANDNAME; --global-options=--debug</userinput>
594
 
        
595
 
      </para>
596
 
    </informalexample>
597
 
    <informalexample>
598
 
      <para>
599
 
        Read a different configuration file, run plugins from a
600
 
        different directory, specify an alternate plugin helper
601
 
        directory and add two options to the
602
 
        <citerefentry><refentrytitle >mandos-client</refentrytitle>
603
 
        <manvolnum>8mandos</manvolnum></citerefentry> plugin:
604
 
      </para>
605
 
      <para>
606
 
 
607
 
<!-- do not wrap this line -->
608
 
<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>
609
 
 
610
 
      </para>
611
 
    </informalexample>
 
438
    <para>
 
439
    </para>
612
440
  </refsect1>
 
441
  
613
442
  <refsect1 id="security">
614
443
    <title>SECURITY</title>
615
444
    <para>
616
 
      This program will, when starting, try to switch to another user.
617
 
      If it is started as root, it will succeed, and will by default
618
 
      switch to user and group 65534, which are assumed to be
619
 
      non-privileged.  This user and group is then what all plugins
620
 
      will be started as.  Therefore, the only way to run a plugin as
621
 
      a privileged user is to have the set-user-ID or set-group-ID bit
622
 
      set on the plugin executable file (see <citerefentry>
623
 
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
624
 
      </citerefentry>).
625
 
    </para>
626
 
    <para>
627
 
      If this program is used as a keyscript in <citerefentry
628
 
      ><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
629
 
      </citerefentry>, there is a slight risk that if this program
630
 
      fails to work, there might be no way to boot the system except
631
 
      for booting from another media and editing the initial RAM disk
632
 
      image to not run this program.  This is, however, unlikely,
633
 
      since the <citerefentry><refentrytitle
634
 
      >password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
635
 
      </citerefentry> plugin will read a password from the console in
636
 
      case of failure of the other plugins, and this plugin runner
637
 
      will also, in case of catastrophic failure, itself fall back to
638
 
      asking and outputting a password on the console (see <xref
639
 
      linkend="fallback"/>).
640
445
    </para>
641
446
  </refsect1>
642
447
  
643
448
  <refsect1 id="see_also">
644
449
    <title>SEE ALSO</title>
645
450
    <para>
646
 
      <citerefentry><refentrytitle>intro</refentrytitle>
647
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
648
451
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
649
452
      <manvolnum>8</manvolnum></citerefentry>,
650
 
      <citerefentry><refentrytitle>crypttab</refentrytitle>
651
 
      <manvolnum>5</manvolnum></citerefentry>,
652
 
      <citerefentry><refentrytitle>execve</refentrytitle>
653
 
      <manvolnum>2</manvolnum></citerefentry>,
654
453
      <citerefentry><refentrytitle>mandos</refentrytitle>
655
454
      <manvolnum>8</manvolnum></citerefentry>,
656
455
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
657
456
      <manvolnum>8mandos</manvolnum></citerefentry>,
658
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
457
      <citerefentry><refentrytitle>password-request</refentrytitle>
659
458
      <manvolnum>8mandos</manvolnum></citerefentry>
660
459
    </para>
661
460
  </refsect1>