/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to plugins.d/mandos-client.xml

  • Committer: Teddy Hogeborn
  • Date: 2019-07-27 10:11:45 UTC
  • mto: This revision was merged to the branch mainline in revision 384.
  • Revision ID: teddy@recompile.se-20190727101145-jnpbpf8220gldbcd
Add dracut(8) support

Add support for the dracut(8) system for generating initramfs image
files; dracut is an alternative to the "initramfs-tools" package.

* .bzrignore (dracut-module/password-agent): Ignore new binary file.
* dracut-module: New directory for the dracut module.
* INSTALL (Prerequisites/Libraries/Mandos Client): Add dracut as an
                                                   alternative to
                                                   initramfs-tools,
                                                   and also add GLib.
* Makefile (DRACUTMODULE, GLIB_CFLAGS, GLIB_LIBS): New.
  (CPROGS): Add "dracut-module/password-agent".
  (DOCS): Add "dracut-module/password-agent.8mandos".
  (dracut-module/password-agent.8mandos): New.
  (dracut-module/password-agent.8mandos.xhtml): - '' -
  (dracut-module/password-agent): - '' -
  (check): Add command to run tests of password-agent(8mandos).
  (install-client-nokey): Also install the dracut module directory,
                          its files, and the password-agent(8mandos)
                          manual page.
  (install-client): To update the initramfs image file, run
                    update-initramfs or dracut depending on what is
                    installed.
  (uninstall-client): - '' - and also uninstall the the files in the
                      dracut module directory, that directory itself,
                      and the password-agent(8mandos) manual page.
* debian/control (Build-Depends): Add "libglib2.0-dev (>=2.40)".
  (Package: mandos-client/Depends): Add "dracut (>= 044+241-3)" as an
                                    alternative dependency to
                                    initramfs-tools.
  (Package: mandos-client/Conflicts): New; set to
                                      "dracut-config-generic".
  (debian/mandos-client.README.Debian): Document alternative commands
                                        to update the initramfs image
                                        for when dracut is used.
* debian/mandos-client.postinst (update_initramfs): Use alternative
                                                    commands to update
                                                    the initramfs
                                                    image for when
                                                    dracut is used.
* debian/tests/control (password-agent, password-agent-suid): Add two
                                                              new tests.
* dracut-module/ask-password-mandos.path: New.
* dracut-module/ask-password-mandos.service: - '' -
* dracut-module/cmdline-mandos.sh: - '' -
* dracut-module/module-setup.sh: - '' -
* dracut-module/password-agent.c: - '' -
* dracut-module/password-agent.xml: - '' -
* initramfs-unpack: Use the dracut "skipcpio" command, if available.
                    Also be more flexible and try hard to detect where
                    compressed data starts.
* plugins.d/mandos-client.xml (SECURITY): Be more precise that the
                                          mandos-client binary might
                                          not always be setuid, but
                                          that the program assumes
                                          that it has been started
                                          that way.
* plugins.d/password-prompt.c: Add new "--prompt" option.
  (conflict_detection): First try to detect the new PID file of
                        plymouth.
  (main): Define and use new "prompt" variable.
* plugins.d/password-prompt.xml (SYNOPSIS): Show new --prompt option.
  (DESCRIPTION): Describe new behavior of looking for plymouth PID
                 file.
  (OPTIONS): Document new "--prompt" option.
  (ENVIRONMENT): Clarify that the CRYPTTAB_SOURCE and CRYPTTAB_NAME
                 environment variables are not used if the --prompt
                 option is used.  Remove unnecessarily specific
                 details about where the CRYPTTAB_SOURCE and
                 CRYPTTAB_NAME comes from, since this can now be
                 either initramfs-tools or dracut.
  (SEE ALSO): Remove superfluous crypttab(5) reference, and add commas
              to separate the other references.
* plugins.d/plymouth.c: Add new "--prompt" and "--debug" options.
  (debug): New global flag.
  (fprintf_plus): New function, used for debug output.
  (exec_and_wait): Add extra "const" to "argv" argument.
  (main): Define and use new "prompt" variable.  Add debug output.
  (main/options, main/parse_opt): New; used to parse options.
* plugins.d/plymouth.xml (SYNOPSIS): Show new options.
  (OPTIONS): Document new options.
  (ENVIRONMENT): Clarify that the cryptsource and crypttarget
                 environment variables are not used if the --prompt
                 option is used.  Remove unnecessarily specific
                 details about where the cryptsource and crypttarget
                 comes from, since this can now be either
                 initramfs-tools or dracut.
  (EXAMPLE): Add an example using an option.
  (SEE ALSO): Remove superfluous crypttab(5) reference.
* plugins.d/splashy.xml (ENVIRONMENT): Clarify that the cryptsource
                                       and crypttarget environment
                                       variables are not used if the
                                       --prompt option is used.
                                       Remove unnecessarily specific
                                       details about where the
                                       cryptsource and crypttarget
                                       comes from, since this can now
                                       be either initramfs-tools or
                                       dracut.
  (SEE ALSO): Remove superfluous crypttab(5) reference.
* plugins.d/usplash.xml (ENVIRONMENT): Clarify that the cryptsource
                                       and crypttarget environment
                                       variables are not used if the
                                       --prompt option is used.
                                       Remove unnecessarily specific
                                       details about where the
                                       cryptsource and crypttarget
                                       comes from, since this can now
                                       be either initramfs-tools or
                                       dracut.
  (SEE ALSO): Remove superfluous crypttab(5) reference.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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 "2023-10-21">
 
5
<!ENTITY TIMESTAMP "2019-07-24">
6
6
<!ENTITY % common SYSTEM "../common.ent">
7
7
%common;
8
8
]>
196
196
    </para>
197
197
    <para>
198
198
      This program is not meant to be run directly; it is really meant
199
 
      to be run by other programs in the initial
200
 
      <acronym>RAM</acronym> disk environment; see <xref
201
 
      linkend="overview"/>.
 
199
      to run as a plugin of the <application>Mandos</application>
 
200
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
201
      <manvolnum>8mandos</manvolnum></citerefentry>, which runs in the
 
202
      initial <acronym>RAM</acronym> disk environment because it is
 
203
      specified as a <quote>keyscript</quote> in the <citerefentry>
 
204
      <refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
 
205
      </citerefentry> file.
202
206
    </para>
203
207
  </refsect1>
204
208
  
216
220
    <title>OPTIONS</title>
217
221
    <para>
218
222
      This program is commonly not invoked from the command line; it
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.
 
223
      is normally started by the <application>Mandos</application>
 
224
      plugin runner, see <citerefentry><refentrytitle
 
225
      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
 
226
      </citerefentry>.  Any command line options this program accepts
 
227
      are therefore normally provided by the plugin runner, and not
 
228
      directly.
223
229
    </para>
224
230
    
225
231
    <variablelist>
476
482
    <title>OVERVIEW</title>
477
483
    <xi:include href="../overview.xml"/>
478
484
    <para>
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.
 
485
      This program is the client part.  It is a plugin started by
 
486
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
487
      <manvolnum>8mandos</manvolnum></citerefentry> which will run in
 
488
      an initial <acronym>RAM</acronym> disk environment.
504
489
    </para>
505
490
    <para>
506
491
      This program could, theoretically, be used as a keyscript in
507
492
      <filename>/etc/crypttab</filename>, but it would then be
508
493
      impossible to enter a password for the encrypted root disk at
509
494
      the console, since this program does not read from the console
510
 
      at all.
 
495
      at all.  This is why a separate plugin runner (<citerefentry>
 
496
      <refentrytitle>plugin-runner</refentrytitle>
 
497
      <manvolnum>8mandos</manvolnum></citerefentry>) is used to run
 
498
      both this program and others in in parallel,
 
499
      <emphasis>one</emphasis> of which (<citerefentry>
 
500
      <refentrytitle>password-prompt</refentrytitle>
 
501
      <manvolnum>8mandos</manvolnum></citerefentry>) will prompt for
 
502
      passwords on the system console.
511
503
    </para>
512
504
  </refsect1>
513
505
  
770
762
    <title>EXAMPLE</title>
771
763
    <para>
772
764
      Note that normally, command line options will not be given
773
 
      directly, but passed on via the program responsible for starting
774
 
      this program; see <xref linkend="overview"/>.
 
765
      directly, but via options for the Mandos <citerefentry
 
766
      ><refentrytitle>plugin-runner</refentrytitle>
 
767
      <manvolnum>8mandos</manvolnum></citerefentry>.
775
768
    </para>
776
769
    <informalexample>
777
770
      <para>
879
872
      <manvolnum>5</manvolnum></citerefentry>,
880
873
      <citerefentry><refentrytitle>mandos</refentrytitle>
881
874
      <manvolnum>8</manvolnum></citerefentry>,
882
 
      <citerefentry><refentrytitle>password-agent</refentrytitle>
 
875
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
883
876
      <manvolnum>8mandos</manvolnum></citerefentry>,
884
877
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
885
878
      <manvolnum>8mandos</manvolnum></citerefentry>