/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 plugins.d/mandos-client.xml

* debian/mandos-client.README.Debian: Document network hook facility.
* debian/mandos-client.docs (network-hooks.d): Added.
* initramfs-tools-hook: Also pass VERBOSITY to network hook.
* plugins.d/mandos-client.xml (DESCRIPTION): Document network
                                             interface selection
                                             algorithm.
  (OPTIONS/--interface): Refer to NETWORK HOOKS section.
  (OVERVIEW): Refer to password-prompt(8mandos) explicitly.
  (NETWORK HOOKS): New section.
  (FILES): Add "/lib/mandos/network-hooks.d".

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugins.d/mandos-client.xml
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
4
<!ENTITY COMMANDNAME "mandos-client">
5
 
<!ENTITY TIMESTAMP "2011-08-08">
 
5
<!ENTITY TIMESTAMP "2011-11-27">
6
6
<!ENTITY % common SYSTEM "../common.ent">
7
7
%common;
8
8
]>
19
19
        <firstname>Björn</firstname>
20
20
        <surname>Påhlsson</surname>
21
21
        <address>
22
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
23
23
        </address>
24
24
      </author>
25
25
      <author>
26
26
        <firstname>Teddy</firstname>
27
27
        <surname>Hogeborn</surname>
28
28
        <address>
29
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
30
30
        </address>
31
31
      </author>
32
32
    </authorgroup>
102
102
      </arg>
103
103
      <sbr/>
104
104
      <arg>
 
105
        <option>--network-hook-dir
 
106
        <replaceable>DIR</replaceable></option>
 
107
      </arg>
 
108
      <sbr/>
 
109
      <arg>
105
110
        <option>--debug</option>
106
111
      </arg>
107
112
    </cmdsynopsis>
143
148
      will wait indefinitely for new servers to appear.
144
149
    </para>
145
150
    <para>
 
151
      The network interface is selected like this: If an interface is
 
152
      specified using the <option>--interface</option> option, that
 
153
      interface is used.  Otherwise, <command>&COMMANDNAME;</command>
 
154
      will choose any interface that is up and running and is not a
 
155
      loopback interface, is not a point-to-point interface, is
 
156
      capable of broadcasting and does not have the NOARP flag (see
 
157
      <citerefentry><refentrytitle>netdevice</refentrytitle>
 
158
      <manvolnum>7</manvolnum></citerefentry>).  (If the
 
159
      <option>--connect</option> option is used, point-to-point
 
160
      interfaces and non-broadcast interfaces are accepted.)  If no
 
161
      acceptable interfaces are found, re-run the check but without
 
162
      the <quote>up and running</quote> requirement, and manually take
 
163
      the selected interface up (and later take it down on program
 
164
      exit).
 
165
    </para>
 
166
    <para>
 
167
      Before a network interface is selected, all <quote>network
 
168
      hooks</quote> are run; see <xref linkend="network-hooks"/>.
 
169
    </para>
 
170
    <para>
146
171
      This program is not meant to be run directly; it is really meant
147
172
      to run as a plugin of the <application>Mandos</application>
148
173
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
223
248
            can not be a pseudo-interface such as <quote>br0</quote>
224
249
            or <quote>tun0</quote>; such interfaces will not exist
225
250
            until much later in the boot process, and can not be used
226
 
            by this program.
 
251
            by this program, unless created by a <quote>network
 
252
            hook</quote> — see <xref linkend="network-hooks"/>.
227
253
          </para>
228
254
          <para>
229
255
            <replaceable>NAME</replaceable> can be the string
311
337
          </para>
312
338
        </listitem>
313
339
      </varlistentry>
 
340
 
 
341
      <varlistentry>
 
342
        <term><option>--network-hook-dir=<replaceable
 
343
        >DIR</replaceable></option></term>
 
344
        <listitem>
 
345
          <para>
 
346
            Network hook directory.  The default directory is
 
347
            <quote><filename class="directory"
 
348
            >/lib/mandos/network-hooks.d</filename></quote>.
 
349
          </para>
 
350
        </listitem>
 
351
      </varlistentry>
314
352
      
315
353
      <varlistentry>
316
354
        <term><option>--debug</option></term>
377
415
      <refentrytitle>plugin-runner</refentrytitle>
378
416
      <manvolnum>8mandos</manvolnum></citerefentry>) is used to run
379
417
      both this program and others in in parallel,
380
 
      <emphasis>one</emphasis> of which will prompt for passwords on
381
 
      the system console.
 
418
      <emphasis>one</emphasis> of which (<citerefentry>
 
419
      <refentrytitle>password-prompt</refentrytitle>
 
420
      <manvolnum>8mandos</manvolnum></citerefentry>) will prompt for
 
421
      passwords on the system console.
382
422
    </para>
383
423
  </refsect1>
384
424
  
405
445
    </para>
406
446
  </refsect1>
407
447
  
 
448
  <refsect1 id="network-hooks">
 
449
    <title>NETWORK HOOKS</title>
 
450
    <para>
 
451
      If a network interface like a bridge or tunnel is required to
 
452
      find a Mandos server, this requires the interface to be up and
 
453
      running before <command>&COMMANDNAME;</command> starts looking
 
454
      for Mandos servers.  This can be accomplished by creating a
 
455
      <quote>network hook</quote> program, and placing it in a special
 
456
      directory.
 
457
    </para>
 
458
    <para>
 
459
      Before the network is used (and again before program exit), any
 
460
      runnable programs found in the network hook directory are run
 
461
      with the argument <quote><literal>start</literal></quote> or
 
462
      <quote><literal>stop</literal></quote>.  This should bring up or
 
463
      down, respectively, any network interface which
 
464
      <command>&COMMANDNAME;</command> should use.
 
465
    </para>
 
466
    <refsect2 id="hook-requirements">
 
467
      <title>REQUIREMENTS</title>
 
468
      <para>
 
469
        A network hook must be an executable file, and its name must
 
470
        consist entirely of upper and lower case letters, digits,
 
471
        underscores, and hyphens.
 
472
      </para>
 
473
      <para>
 
474
        A network hook will receive one argument, which can be one of
 
475
        the following:
 
476
      </para>
 
477
      <variablelist>
 
478
        <varlistentry>
 
479
          <term><literal>start</literal></term>
 
480
          <listitem>
 
481
            <para>
 
482
              This should make the network hook create (if necessary)
 
483
              and bring up a network interface.
 
484
            </para>
 
485
          </listitem>
 
486
        </varlistentry>
 
487
        <varlistentry>
 
488
          <term><literal>stop</literal></term>
 
489
          <listitem>
 
490
            <para>
 
491
              This should make the network hook take down a network
 
492
              interface, and delete it if it did not exist previously.
 
493
            </para>
 
494
          </listitem>
 
495
        </varlistentry>
 
496
        <varlistentry>
 
497
          <term><literal>files</literal></term>
 
498
          <listitem>
 
499
            <para>
 
500
              This should make the network hook print, <emphasis>on
 
501
              separate lines</emphasis>, all the files needed for it
 
502
              to run.  (These files will be copied into the initial
 
503
              RAM filesystem.)  Intended use is for a network hook
 
504
              which is a shell script to print its needed binaries.
 
505
            </para>
 
506
            <para>
 
507
              It is not necessary to print any non-executable files
 
508
              already in the network hook directory, these will be
 
509
              copied implicitly if they otherwise satisfy the name
 
510
              requirement.
 
511
            </para>
 
512
          </listitem>
 
513
        </varlistentry>
 
514
      </variablelist>
 
515
      <para>
 
516
        The network hook will be provided with a number of environment
 
517
        variables:
 
518
      </para>
 
519
      <variablelist>
 
520
        <varlistentry>
 
521
          <term><envar>MANDOSNETHOOKDIR</envar></term>
 
522
          <listitem>
 
523
            <para>
 
524
              The network hook directory, specified to
 
525
              <command>&COMMANDNAME;</command> by the
 
526
              <option>--network-hook-dir</option> option.  Note: this
 
527
              should <emphasis>always</emphasis> be used by the
 
528
              network hook to refer to itself or any files it may
 
529
              require.
 
530
            </para>
 
531
          </listitem>
 
532
        </varlistentry>
 
533
        <varlistentry>
 
534
          <term><envar>DEVICE</envar></term>
 
535
          <listitem>
 
536
            <para>
 
537
              The network interface, as specified to
 
538
              <command>&COMMANDNAME;</command> by the
 
539
              <option>--interface</option> option.  If this is not the
 
540
              interface a hook will bring up, there is no reason for a
 
541
              hook to continue.
 
542
            </para>
 
543
          </listitem>
 
544
        </varlistentry>
 
545
        <varlistentry>
 
546
          <term><envar>MODE</envar></term>
 
547
          <listitem>
 
548
            <para>
 
549
              This will be the same as the first argument;
 
550
              i.e. <quote><literal>start</literal></quote>,
 
551
              <quote><literal>stop</literal></quote>, or
 
552
              <quote><literal>files</literal></quote>.
 
553
            </para>
 
554
          </listitem>
 
555
        </varlistentry>
 
556
        <varlistentry>
 
557
          <term><envar>VERBOSITY</envar></term>
 
558
          <listitem>
 
559
            <para>
 
560
              This will be the <quote><literal>1</literal></quote> if
 
561
              the <option>--debug</option> option is passed to
 
562
              <command>&COMMANDNAME;</command>, otherwise
 
563
              <quote><literal>0</literal></quote>.
 
564
            </para>
 
565
          </listitem>
 
566
        </varlistentry>
 
567
        <varlistentry>
 
568
          <term><envar>DELAY</envar></term>
 
569
          <listitem>
 
570
            <para>
 
571
              This will be the same as the <option>--delay</option>
 
572
              option passed to <command>&COMMANDNAME;</command>.
 
573
            </para>
 
574
          </listitem>
 
575
        </varlistentry>
 
576
      </variablelist>
 
577
      <para>
 
578
        A hook may not read from standard input, and should be
 
579
        restrictive in printing to standard output or standard error
 
580
        unless <varname>VERBOSITY</varname> is
 
581
        <quote><literal>1</literal></quote>.
 
582
      </para>
 
583
    </refsect2>
 
584
  </refsect1>
 
585
  
408
586
  <refsect1 id="files">
409
587
    <title>FILES</title>
410
588
    <variablelist>
422
600
          </para>
423
601
        </listitem>
424
602
      </varlistentry>
 
603
      <varlistentry>
 
604
        <term><filename
 
605
        class="directory">/lib/mandos/network-hooks.d</filename></term>
 
606
        <listitem>
 
607
          <para>
 
608
            Directory where network hooks are located.  Change this
 
609
            with the <option>--network-hook-dir</option> option.  See
 
610
            <xref linkend="network-hooks"/>.
 
611
          </para>
 
612
        </listitem>
 
613
      </varlistentry>
425
614
    </variablelist>
426
615
  </refsect1>
427
616