/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: 2015-08-10 10:42:52 UTC
  • Revision ID: teddy@recompile.se-20150810104252-1r6yyfwkvh5t60bz
Server Bug fix: Make D-Bus introspection work again.

* mandos (DBusObjectWithObjectManager.Introspect): Bug fix; call
                                                   method Introspect,
                                                   not class
                                                   DBusObjectWithAnnotations.
  (alternate_dbus_interfaces/wrapper/fixscope): Make wrapped D-Bus
                                                signal function look
                                                like a D-Bus signal so
                                                Introspect can see it.

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">
5
4
<!ENTITY COMMANDNAME "plugin-runner">
6
 
<!ENTITY TIMESTAMP "2008-09-02">
 
5
<!ENTITY TIMESTAMP "2015-07-20">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
    <title>Mandos Manual</title>
12
13
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
18
19
        <firstname>Björn</firstname>
19
20
        <surname>Påhlsson</surname>
20
21
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
22
23
        </address>
23
24
      </author>
24
25
      <author>
25
26
        <firstname>Teddy</firstname>
26
27
        <surname>Hogeborn</surname>
27
28
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
29
30
        </address>
30
31
      </author>
31
32
    </authorgroup>
32
33
    <copyright>
33
34
      <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>
34
42
      <holder>Teddy Hogeborn</holder>
35
43
      <holder>Björn Påhlsson</holder>
36
44
    </copyright>
37
45
    <xi:include href="legalnotice.xml"/>
38
46
  </refentryinfo>
39
 
 
 
47
  
40
48
  <refmeta>
41
49
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
50
    <manvolnum>8mandos</manvolnum>
45
53
  <refnamediv>
46
54
    <refname><command>&COMMANDNAME;</command></refname>
47
55
    <refpurpose>
48
 
      Run Mandos plugins.  Pass data from first succesful one.
 
56
      Run Mandos plugins, pass data from first to succeed.
49
57
    </refpurpose>
50
58
  </refnamediv>
51
 
 
 
59
  
52
60
  <refsynopsisdiv>
53
61
    <cmdsynopsis>
54
62
      <command>&COMMANDNAME;</command>
55
63
      <group rep="repeat">
56
64
        <arg choice="plain"><option>--global-env=<replaceable
57
 
        >VAR</replaceable><literal>=</literal><replaceable
 
65
        >ENV</replaceable><literal>=</literal><replaceable
58
66
        >value</replaceable></option></arg>
59
67
        <arg choice="plain"><option>-G
60
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
68
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
61
69
        >value</replaceable> </option></arg>
62
70
      </group>
63
71
      <sbr/>
111
119
      <arg><option>--plugin-dir=<replaceable
112
120
      >DIRECTORY</replaceable></option></arg>
113
121
      <sbr/>
 
122
      <arg><option>--plugin-helper-dir=<replaceable
 
123
      >DIRECTORY</replaceable></option></arg>
 
124
      <sbr/>
114
125
      <arg><option>--config-file=<replaceable
115
126
      >FILE</replaceable></option></arg>
116
127
      <sbr/>
140
151
    <title>DESCRIPTION</title>
141
152
    <para>
142
153
      <command>&COMMANDNAME;</command> is a program which is meant to
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.
 
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.
150
161
    </para>
151
162
    <para>
152
163
      This program is not meant to be invoked directly, but can be in
170
181
    <variablelist>
171
182
      <varlistentry>
172
183
        <term><option>--global-env
173
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
184
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
174
185
        >value</replaceable></option></term>
175
 
        <term><option>-e
176
 
        <replaceable>VAR</replaceable><literal>=</literal><replaceable
 
186
        <term><option>-G
 
187
        <replaceable>ENV</replaceable><literal>=</literal><replaceable
177
188
        >value</replaceable></option></term>
178
189
        <listitem>
179
190
          <para>
189
200
        <replaceable>PLUGIN</replaceable><literal>:</literal
190
201
        ><replaceable>ENV</replaceable><literal>=</literal
191
202
        ><replaceable>value</replaceable></option></term>
192
 
        <term><option>-f
 
203
        <term><option>-E
193
204
        <replaceable>PLUGIN</replaceable><literal>:</literal
194
205
        ><replaceable>ENV</replaceable><literal>=</literal
195
206
        ><replaceable>value</replaceable></option></term>
215
226
            <replaceable>OPTIONS</replaceable> is a comma separated
216
227
            list of options.  This is not a very useful option, except
217
228
            for specifying the <quote><option>--debug</option></quote>
218
 
            for all plugins.
 
229
            option to all plugins.
219
230
          </para>
220
231
        </listitem>
221
232
      </varlistentry>
241
252
            <option>--bar</option> with the option argument
242
253
            <quote>baz</quote> is either
243
254
            <userinput>--options-for=foo:--bar=baz</userinput> or
244
 
            <userinput>--options-for=foo:--bar,baz</userinput>, but
245
 
            <emphasis>not</emphasis>
246
 
            <userinput>--options-for="foo:--bar baz"</userinput>.
 
255
            <userinput>--options-for=foo:--bar,baz</userinput>.  Using
 
256
            <userinput>--options-for="foo:--bar baz"</userinput>. will
 
257
            <emphasis>not</emphasis> work.
247
258
          </para>
248
259
        </listitem>
249
260
      </varlistentry>
250
 
 
 
261
      
251
262
      <varlistentry>
252
263
        <term><option>--disable
253
264
        <replaceable>PLUGIN</replaceable></option></term>
258
269
            Disable the plugin named
259
270
            <replaceable>PLUGIN</replaceable>.  The plugin will not be
260
271
            started.
261
 
          </para>       
 
272
          </para>
262
273
        </listitem>
263
274
      </varlistentry>
264
 
 
 
275
      
265
276
      <varlistentry>
266
277
        <term><option>--enable
267
278
        <replaceable>PLUGIN</replaceable></option></term>
272
283
            Re-enable the plugin named
273
284
            <replaceable>PLUGIN</replaceable>.  This is only useful to
274
285
            undo a previous <option>--disable</option> option, maybe
275
 
            from the config file.
 
286
            from the configuration file.
276
287
          </para>
277
288
        </listitem>
278
289
      </varlistentry>
279
 
 
 
290
      
280
291
      <varlistentry>
281
292
        <term><option>--groupid
282
293
        <replaceable>ID</replaceable></option></term>
289
300
          </para>
290
301
        </listitem>
291
302
      </varlistentry>
292
 
 
 
303
      
293
304
      <varlistentry>
294
305
        <term><option>--userid
295
306
        <replaceable>ID</replaceable></option></term>
302
313
          </para>
303
314
        </listitem>
304
315
      </varlistentry>
305
 
 
 
316
      
306
317
      <varlistentry>
307
318
        <term><option>--plugin-dir
308
319
        <replaceable>DIRECTORY</replaceable></option></term>
317
328
      </varlistentry>
318
329
      
319
330
      <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>
320
346
        <term><option>--config-file
321
347
        <replaceable>FILE</replaceable></option></term>
322
348
        <listitem>
365
391
          </para>
366
392
        </listitem>
367
393
      </varlistentry>
368
 
 
 
394
      
369
395
      <varlistentry>
370
396
        <term><option>--version</option></term>
371
397
        <term><option>-V</option></term>
377
403
      </varlistentry>
378
404
    </variablelist>
379
405
  </refsect1>
380
 
 
 
406
  
381
407
  <refsect1 id="overview">
382
408
    <title>OVERVIEW</title>
383
409
    <xi:include href="overview.xml"/>
403
429
      code will make this plugin-runner output the password from that
404
430
      plugin, stop any other plugins, and exit.
405
431
    </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>
406
474
  </refsect1>
407
475
  
408
476
  <refsect1 id="fallback">
434
502
      only passes on its environment to all the plugins.  The
435
503
      environment passed to plugins can be modified using the
436
504
      <option>--global-env</option> and <option>--env-for</option>
437
 
      optins.
 
505
      options.  Also, the <option>--plugin-helper-dir</option> option
 
506
      will affect the environment variable
 
507
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
438
508
    </para>
439
509
  </refsect1>
440
510
  
480
550
  <refsect1 id="bugs">
481
551
    <title>BUGS</title>
482
552
    <para>
 
553
      The <option>--config-file</option> option is ignored when
 
554
      specified from within a configuration file.
483
555
    </para>
484
556
  </refsect1>
485
557
  
486
558
  <refsect1 id="examples">
487
559
    <title>EXAMPLE</title>
488
 
    <para>
489
 
    </para>
 
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>
490
617
  </refsect1>
491
 
  
492
618
  <refsect1 id="security">
493
619
    <title>SECURITY</title>
494
620
    <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"/>).
495
645
    </para>
496
646
  </refsect1>
497
647
  
498
648
  <refsect1 id="see_also">
499
649
    <title>SEE ALSO</title>
500
650
    <para>
 
651
      <citerefentry><refentrytitle>intro</refentrytitle>
 
652
      <manvolnum>8mandos</manvolnum></citerefentry>,
501
653
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
502
654
      <manvolnum>8</manvolnum></citerefentry>,
 
655
      <citerefentry><refentrytitle>crypttab</refentrytitle>
 
656
      <manvolnum>5</manvolnum></citerefentry>,
 
657
      <citerefentry><refentrytitle>execve</refentrytitle>
 
658
      <manvolnum>2</manvolnum></citerefentry>,
503
659
      <citerefentry><refentrytitle>mandos</refentrytitle>
504
660
      <manvolnum>8</manvolnum></citerefentry>,
505
661
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
506
662
      <manvolnum>8mandos</manvolnum></citerefentry>,
507
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
663
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
508
664
      <manvolnum>8mandos</manvolnum></citerefentry>
509
665
    </para>
510
666
  </refsect1>