/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

  • Committer: Teddy Hogeborn
  • Date: 2024-09-08 00:08:15 UTC
  • Revision ID: teddy@recompile.se-20240908000815-x3gr5xion3kyyoio
Improve documentation

* mandos.conf.xml (DESCRIPTION): Remove the unnecessary word "simple".
* plugin-runner.xml (PLUGINS): Remove the unnecessary word "simply",
  and add the "executable" qualifier to the description of plugins.
* mandos-client.xml (DESCRIPTION, OPTIONS): Do not refer to
  "plugin-runner"; instead refer to the section "OVERVIEW".
  (OVERVIEW): Don't only describe plugin-runner; also describe
  how password-agent can start mandos-client.
  (EXAMPLE): Do not refer to "plugin-runner"; instead refer to the
  section "OVERVIEW".
  (SEE ALSO): Replace reference to "password-prompt" with
  "password-agent".

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 "2019-02-09">
 
5
<!ENTITY TIMESTAMP "2023-10-21">
6
6
<!ENTITY % common SYSTEM "../common.ent">
7
7
%common;
8
8
]>
42
42
      <year>2016</year>
43
43
      <year>2017</year>
44
44
      <year>2018</year>
 
45
      <year>2019</year>
45
46
      <holder>Teddy Hogeborn</holder>
46
47
      <holder>Björn Påhlsson</holder>
47
48
    </copyright>
195
196
    </para>
196
197
    <para>
197
198
      This program is not meant to be run directly; it is really meant
198
 
      to run as a plugin of the <application>Mandos</application>
199
 
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
200
 
      <manvolnum>8mandos</manvolnum></citerefentry>, which runs in the
201
 
      initial <acronym>RAM</acronym> disk environment because it is
202
 
      specified as a <quote>keyscript</quote> in the <citerefentry>
203
 
      <refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
204
 
      </citerefentry> file.
 
199
      to be run by other programs in the initial
 
200
      <acronym>RAM</acronym> disk environment; see <xref
 
201
      linkend="overview"/>.
205
202
    </para>
206
203
  </refsect1>
207
204
  
219
216
    <title>OPTIONS</title>
220
217
    <para>
221
218
      This program is commonly not invoked from the command line; it
222
 
      is normally started by the <application>Mandos</application>
223
 
      plugin runner, see <citerefentry><refentrytitle
224
 
      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
225
 
      </citerefentry>.  Any command line options this program accepts
226
 
      are therefore normally provided by the plugin runner, and not
227
 
      directly.
 
219
      is normally started by another program as described in <xref
 
220
      linkend="description"/>.  Any command line options this program
 
221
      accepts are therefore normally provided by the invoking program,
 
222
      and not directly.
228
223
    </para>
229
224
    
230
225
    <variablelist>
481
476
    <title>OVERVIEW</title>
482
477
    <xi:include href="../overview.xml"/>
483
478
    <para>
484
 
      This program is the client part.  It is a plugin started by
485
 
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
486
 
      <manvolnum>8mandos</manvolnum></citerefentry> which will run in
487
 
      an initial <acronym>RAM</acronym> disk environment.
 
479
      This program is the client part.  It is run automatically in an
 
480
      initial <acronym>RAM</acronym> disk environment.
 
481
    </para>
 
482
    <para>
 
483
      In an initial <acronym>RAM</acronym> disk environment using
 
484
      <citerefentry><refentrytitle>systemd</refentrytitle>
 
485
      <manvolnum>1</manvolnum></citerefentry>, this program is started
 
486
      by the <application>Mandos</application> <citerefentry>
 
487
      <refentrytitle>password-agent</refentrytitle>
 
488
      <manvolnum>8mandos</manvolnum></citerefentry>, which in turn is
 
489
      started automatically by the <citerefentry>
 
490
      <refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum>
 
491
      </citerefentry> <quote>Password Agent</quote> system.
 
492
    </para>
 
493
    <para>
 
494
      In the case of a non-<citerefentry>
 
495
      <refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum>
 
496
      </citerefentry> environment, this program is started as a plugin
 
497
      of the <application>Mandos</application> <citerefentry>
 
498
      <refentrytitle>plugin-runner</refentrytitle>
 
499
      <manvolnum>8mandos</manvolnum></citerefentry>, which runs in the
 
500
      initial <acronym>RAM</acronym> disk environment because it is
 
501
      specified as a <quote>keyscript</quote> in the <citerefentry>
 
502
      <refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
 
503
      </citerefentry> file.
488
504
    </para>
489
505
    <para>
490
506
      This program could, theoretically, be used as a keyscript in
491
507
      <filename>/etc/crypttab</filename>, but it would then be
492
508
      impossible to enter a password for the encrypted root disk at
493
509
      the console, since this program does not read from the console
494
 
      at all.  This is why a separate plugin runner (<citerefentry>
495
 
      <refentrytitle>plugin-runner</refentrytitle>
496
 
      <manvolnum>8mandos</manvolnum></citerefentry>) is used to run
497
 
      both this program and others in in parallel,
498
 
      <emphasis>one</emphasis> of which (<citerefentry>
499
 
      <refentrytitle>password-prompt</refentrytitle>
500
 
      <manvolnum>8mandos</manvolnum></citerefentry>) will prompt for
501
 
      passwords on the system console.
 
510
      at all.
502
511
    </para>
503
512
  </refsect1>
504
513
  
524
533
          <para>
525
534
            This environment variable will be assumed to contain the
526
535
            directory containing any helper executables.  The use and
527
 
            nature of these helper executables, if any, is
528
 
            purposefully not documented.
 
536
            nature of these helper executables, if any, is purposely
 
537
            not documented.
529
538
        </para>
530
539
        </listitem>
531
540
      </varlistentry>
761
770
    <title>EXAMPLE</title>
762
771
    <para>
763
772
      Note that normally, command line options will not be given
764
 
      directly, but via options for the Mandos <citerefentry
765
 
      ><refentrytitle>plugin-runner</refentrytitle>
766
 
      <manvolnum>8mandos</manvolnum></citerefentry>.
 
773
      directly, but passed on via the program responsible for starting
 
774
      this program; see <xref linkend="overview"/>.
767
775
    </para>
768
776
    <informalexample>
769
777
      <para>
815
823
  <refsect1 id="security">
816
824
    <title>SECURITY</title>
817
825
    <para>
818
 
      This program is set-uid to root, but will switch back to the
819
 
      original (and presumably non-privileged) user and group after
820
 
      bringing up the network interface.
 
826
      This program assumes that it is set-uid to root, and will switch
 
827
      back to the original (and presumably non-privileged) user and
 
828
      group after bringing up the network interface.
821
829
    </para>
822
830
    <para>
823
831
      To use this program for its intended purpose (see <xref
871
879
      <manvolnum>5</manvolnum></citerefentry>,
872
880
      <citerefentry><refentrytitle>mandos</refentrytitle>
873
881
      <manvolnum>8</manvolnum></citerefentry>,
874
 
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
 
882
      <citerefentry><refentrytitle>password-agent</refentrytitle>
875
883
      <manvolnum>8mandos</manvolnum></citerefentry>,
876
884
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
877
885
      <manvolnum>8mandos</manvolnum></citerefentry>
890
898
      </varlistentry>
891
899
      <varlistentry>
892
900
        <term>
893
 
          <ulink url="http://www.avahi.org/">Avahi</ulink>
 
901
          <ulink url="https://www.avahi.org/">Avahi</ulink>
894
902
        </term>
895
903
      <listitem>
896
904
        <para>