Adding debian version 2:2.1.0-5+deb10u2.debian/2%2.1.0-5+deb10u2debian

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

8 files changed, 1308 insertions, 0 deletions

diff --git a/debian/doc/cryptdisks_start.xml b/debian/doc/cryptdisks_start.xml
new file mode 100644
index 0000000..fd8269d
--- /dev/null
+++ b/debian/doc/cryptdisks_start.xml
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd">
+
+<refentry id="command.cryptdisks_start">
+
+ <xi:include href="variables.xml"
+	     xpointer="xpointer(/refentry/refentryinfo)"
+	     xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <refmeta>
+  <refentrytitle>cryptdisks_start</refentrytitle>
+  <manvolnum>8</manvolnum>
+  <xi:include href="variables.xml"
+	      xpointer="xpointer(/refentry/refmeta/*)"
+	      xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ </refmeta>
+
+ <refnamediv>
+  <refname>cryptdisks_start</refname>
+  <refpurpose>wrapper around cryptsetup that parses /etc/crypttab.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+  <simpara>
+   <emphasis role="strong">cryptdisks_start</emphasis>
+   <emphasis>&lt;name&gt;</emphasis>
+  </simpara>
+ </refsynopsisdiv>
+
+ <refsect1 id="cryptdisks_start.description">
+  <title>DESCRIPTION</title>
+  <simpara>
+   <emphasis role="strong">cryptdisks_start</emphasis> is a wrapper around
+   <emphasis role="strong">cryptsetup</emphasis> that parses
+   <emphasis role="strong">/etc/crypttab</emphasis> just like the initscript
+   /etc/init.d/cryptdisks does and starts the dm-crypt mapping that
+   corresponds to <emphasis>&lt;name&gt;</emphasis>.
+  </simpara>
+  <simpara>
+   Note that this wrapper passes <option>--key-file=-</option> to
+   <command moreinfo="refentry">cryptsetup</command>, so the passphrase
+   in any referenced key file must not be followed by a newline character.
+  </simpara>
+ </refsect1>
+
+ <refsect1 id="cryptdisks_start.see_also">
+  <title>SEE ALSO</title>
+  <simpara>
+   <emphasis>cryptdisks_stop</emphasis>(8),
+   <emphasis>cryptsetup</emphasis>(8), <emphasis>crypttab</emphasis>(5)
+  </simpara>
+ </refsect1>
+
+ <refsect1 id="cryptdisks_start.author">
+  <title>AUTHOR</title><simpara>This manual page was written by Jonas Meurer
+   &lt;mejo@debian.org&gt; in December 2007.
+  </simpara>
+ </refsect1>
+
+</refentry>
diff --git a/debian/doc/cryptdisks_stop.xml b/debian/doc/cryptdisks_stop.xml
new file mode 100644
index 0000000..429493f
--- /dev/null
+++ b/debian/doc/cryptdisks_stop.xml
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd">
+
+<refentry id="command.cryptdisks_stop">
+
+ <xi:include href="variables.xml"
+	     xpointer="xpointer(/refentry/refentryinfo)"
+	     xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <refmeta>
+  <refentrytitle>cryptdisk_stop</refentrytitle>
+  <manvolnum>8</manvolnum>
+  <xi:include href="variables.xml"
+	      xpointer="xpointer(/refentry/refmeta/*)"
+	      xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ </refmeta>
+
+ <refnamediv>
+  <refname>cryptdisks_stop</refname>
+  <refpurpose>wrapper around cryptsetup that parses /etc/crypttab.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+  <simpara>
+   <emphasis role="strong">cryptdisks_stop</emphasis>
+   <emphasis>&lt;name&gt;</emphasis>
+  </simpara>
+ </refsynopsisdiv>
+
+ <refsect1 id="cryptdisks_stop.description">
+  <title>DESCRIPTION</title>
+  <simpara>
+   <emphasis role="strong">cryptdisks_stop</emphasis> is a wrapper around
+   <emphasis role="strong">cryptsetup</emphasis> that parses
+   <emphasis role="strong">/etc/crypttab</emphasis> just like the initscript
+   /etc/init.d/cryptdisks does and stops the dm-crypt mapping that corresponds
+   to <emphasis>&lt;name&gt;</emphasis>.
+  </simpara>
+ </refsect1>
+
+ <refsect1 id="cryptdisks_stop.see_also">
+  <title>SEE ALSO</title>
+  <simpara>
+   <emphasis>cryptdisks_start</emphasis>(8),
+   <emphasis>cryptsetup</emphasis>(8), <emphasis>crypttab</emphasis>(5)
+  </simpara>
+ </refsect1>
+
+ <refsect1 id="cryptdisks_stop.author">
+  <title>AUTHOR</title><simpara>This manual page was written by Jonas Meurer
+   &lt;mejo@debian.org&gt; in January 2008.
+  </simpara>
+ </refsect1>
+
+</refentry>
diff --git a/debian/doc/crypttab.xml b/debian/doc/crypttab.xml
new file mode 100644
index 0000000..5f8c961
--- /dev/null
+++ b/debian/doc/crypttab.xml
@@ -0,0 +1,717 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd">
+
+<refentry id="file.crypttab">
+
+ <xi:include href="variables.xml"
+             xpointer="xpointer(/refentry/refentryinfo)"
+             xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <refmeta>
+  <refentrytitle>crypttab</refentrytitle>
+  <manvolnum>5</manvolnum>
+  <xi:include href="variables.xml"
+              xpointer="xpointer(/refentry/refmeta/*)"
+              xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ </refmeta>
+
+ <refnamediv>
+  <refname>crypttab</refname>
+  <refpurpose>static information about encrypted filesystems</refpurpose>
+ </refnamediv>
+
+ <refsect1 id="crypttab.description">
+  <title>DESCRIPTION</title>
+  <simpara>
+   The file <filename>/etc/crypttab</filename> contains descriptive
+   information about encrypted filesystems. <filename>crypttab</filename>
+   is only read by programs (e.g.
+   <command moreinfo="refentry">cryptdisks_start</command> and
+   <command moreinfo="refentry">cryptdisks_stop</command>),
+   and not written; it is the duty of the system
+   administrator to properly create and maintain this file. Each filesystem is
+   described on a separate line; fields on each line are separated by tabs or
+   spaces. Lines starting with <quote>#</quote> are comments, empty lines are
+   ignored. The order of records in <filename>crypttab</filename> is important
+   because the init scripts sequentially iterate through
+   <filename>crypttab</filename> doing their thing.
+  </simpara>
+  <simpara>
+   The first field, <emphasis>target</emphasis>, describes the mapped
+   device name. It must be a plain filename without any directory components.
+   A mapped device which encrypts/decrypts data to/from the <emphasis>source
+   device</emphasis> will be created at
+   <filename class="devicefile">/dev/mapper/target</filename> by
+   <command moreinfo="refentry">cryptsetup</command>.
+  </simpara>
+  <simpara>
+   The second field, <emphasis>source device</emphasis>, describes either the
+   block special device or file that contains the encrypted data. Instead of
+   giving the <emphasis>source device</emphasis> explicitly, the UUID
+   (resp. LABEL, PARTUUID and PARTLABEL) is supported as well, using <quote>UUID=&lt;uuid&gt;</quote>
+   (resp. <quote>LABEL=&lt;label&gt;</quote>, <quote>PARTUUID=&lt;partuuid&gt;</quote>
+   and <quote>PARTLABEL=&lt;partlabel&gt;</quote>).
+  </simpara>
+  <simpara>
+   The third field, <emphasis>key file</emphasis>, describes the file to use
+   as a key for decrypting the data of the <emphasis>source device</emphasis>.
+   In case of a <emphasis>keyscript</emphasis>, the value of this field is
+   given as argument to the keyscript. Values with spaces and special
+   characters need to be escaped using octal sequences, like for
+   <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+   Note that the <emphasis>entire</emphasis> key file will be used as the
+   passphrase; the passphrase must <emphasis>not</emphasis> be followed by a
+   newline character.
+  </simpara>
+  <simpara>
+   It can also be a device name (e.g.
+   <filename class="devicefile">/dev/urandom</filename>), note however that
+   LUKS requires a persistent key and therefore does <emphasis>not</emphasis>
+   support random data keys.
+  </simpara>
+  <simpara>
+   If the <emphasis>key file</emphasis> is the string
+   <emphasis>none</emphasis>, a passphrase will be read interactively from the
+   console. In this case, the options check, checkargs and tries may be
+   useful.
+  </simpara>
+  <simpara>
+   The fourth field, <emphasis>options</emphasis>, describes the cryptsetup
+   options associated with the encryption process. At minimum, the field should
+   contain either the string <emphasis>luks</emphasis> respectively
+   <emphasis>tcrypt</emphasis> or the <emphasis>cipher</emphasis>,
+   <emphasis>hash</emphasis> and <emphasis>size</emphasis> options.
+   Some options can be changed on active devices using
+   <command>cryptsetup refresh [&lt;options&gt;] &lt;name&gt;</command>.
+   Moreover some options can be permanently written to the metada of LUKS2
+   headers using the <command>--persistent</command> option flag.
+  </simpara>
+  <simpara>
+   Options are in the format: <emphasis>key</emphasis>=<emphasis>value</emphasis>
+   [,<emphasis>key</emphasis>=<emphasis>value</emphasis> &#8230;]. The
+   supported options are described below.
+  </simpara>
+  <simpara>
+   Note that all four fields are mandatory and that a missing field will lead
+   to unspecified behaviour.
+  </simpara>
+ </refsect1>
+
+ <refsect1 id="crypttab.implementations">
+  <title>ON DIFFERENT CRYPTTAB FORMATS</title>
+  <simpara>
+   Please note that there are several independent cryptsetup wrappers with
+   their own <emphasis>crypttab</emphasis> format. This manpage covers
+   Debian's implementation for <emphasis>initramfs</emphasis> scripts and
+   <emphasis>SysVinit</emphasis> init scripts. <emphasis>systemd</emphasis>
+   brings its own <emphasis>crypttab</emphasis> implementation.
+   We try to cover the differences between the <emphasis>systemd</emphasis> and
+   our implementation in this manpage, but if in doubt, better check the
+   <emphasis>systemd</emphasis>
+   <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+   manpage, e.g. online at
+   <ulink url="https://www.freedesktop.org/software/systemd/man/crypttab.html"/>.
+  </simpara>
+ </refsect1>
+
+ <refsect1 id="crypttab.options">
+  <title>OPTIONS</title>
+  <variablelist>
+
+   <varlistentry>
+    <term><emphasis>cipher</emphasis>=&lt;cipher&gt;</term>
+    <listitem>
+     <simpara>
+      Encryption algorithm (ignored for LUKS and TCRYPT devices). See
+      <command>cryptsetup -c</command>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>size</emphasis>=&lt;size&gt;</term>
+    <listitem>
+     <simpara>
+      Encryption key size (ignored for LUKS and TCRYPT devices). See
+      <command>cryptsetup -s</command>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>sector-size</emphasis>=&lt;bytes&gt;</term>
+    <listitem>
+     <simpara>
+      Sector size. See
+      <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      for possible values and the default value of this option.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>hash</emphasis>=&lt;hash&gt;</term>
+    <listitem>
+     <simpara>
+      Hash algorithm (ignored for LUKS and TCRYPT devices). See
+      <command>cryptsetup -h</command>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>offset</emphasis>=&lt;offset&gt;</term>
+    <listitem>
+     <simpara>
+      Start offset (ignored for LUKS and TCRYPT devices). Uses
+      <emphasis role="strong">cryptsetup -o</emphasis>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>skip</emphasis>=&lt;skip&gt;</term>
+    <listitem>
+     <simpara>
+      Skip sectors at the beginning (ignored for LUKS and TCRYPT devices).
+      Uses <emphasis role="strong">cryptsetup -p</emphasis>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>keyfile-offset</emphasis>=&lt;keyfile-offset&gt;</term>
+    <listitem>
+     <simpara>
+      Specifies the number of bytes to skip at the start of the key file.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>keyfile-size</emphasis>=&lt;keyfile-size&gt;</term>
+    <listitem>
+     <simpara>
+      Specifies the maximum number of bytes to read from the key file.
+      The default is to read the whole file up to the compiled-in maximum,
+      that can be queried with <emphasis role="strong">cryptsetup --help</emphasis>.
+      This option is ignored for plain dm-crypt devices, as the key file
+      size is then given by the encryption key size (option
+      <emphasis>size</emphasis>).
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>keyslot</emphasis>=&lt;slot&gt;, <emphasis>key-slot</emphasis>=&lt;slot&gt;</term>
+    <listitem>
+     <simpara>
+      Key slot (ignored for non-LUKS devices). See <command>cryptsetup
+      -S</command>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>header</emphasis>=&lt;path&gt;</term>
+    <listitem>
+     <simpara>
+      Detached header file (ignored for plain dm-crypt devices). See
+      <command>cryptsetup --header</command>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>verify</emphasis></term>
+    <listitem>
+     <simpara>
+      Verify password. Uses <emphasis role="strong">cryptsetup -y</emphasis>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>readonly</emphasis>, <emphasis>read-only</emphasis></term>
+    <listitem>
+     <simpara>Set up a read-only mapping.</simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>tries</emphasis>=&lt;num&gt;</term>
+    <listitem>
+     <simpara>Try to unlock the device &lt;num&gt; before failing. It's
+      particularly useful when using a passphrase or a
+      <emphasis>keyscript</emphasis> that asks for interactive input. If you
+      want to disable retries, pass <quote>tries=1</quote>. Default is
+      <quote>3</quote>. Setting <quote>tries=0</quote> means infinitive
+      retries.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>discard</emphasis></term>
+    <listitem>
+     <simpara>Allow using of discards (TRIM) requests for device.</simpara>
+     <simpara>Starting with Debian 10 (Buster), this option is added per
+      default to new dm-crypt devices by the Debian Installer. If you
+      don't care about leaking access patterns (filesystem type, used
+      space) and don't have hidden truecrypt volumes inside this volume,
+      then it should be safe to enable this option. See the following
+      warning for further information.</simpara>
+     <simpara><emphasis role="strong">WARNING</emphasis>: Assess the
+      specific security risks carefully before enabling this option.
+      For example, allowing discards on encrypted devices may lead to
+      the leak of information about the ciphertext device (filesystem
+      type, used space etc.) if the discarded blocks can be located
+      easily on the device later.</simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>luks</emphasis></term>
+    <listitem>
+     <simpara>Force LUKS mode. When this mode is used, the following options
+      are ignored since they are provided by the LUKS header on the device:
+      <emphasis>cipher=</emphasis>, <emphasis>hash=</emphasis>,
+     <emphasis>size=</emphasis></simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>plain</emphasis></term>
+    <listitem>
+     <simpara>Force plain encryption mode.</simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>tcrypt</emphasis></term>
+    <listitem>
+     <simpara>Use TrueCrypt encryption mode. When this mode is used, the
+      following options are ignored since they are provided by the TrueCrypt
+      header on the device or do not apply: <emphasis>cipher=</emphasis>,
+      <emphasis>hash=</emphasis>, <emphasis>keyfile-offset=</emphasis>,
+      <emphasis>keyfile-size=</emphasis>, <emphasis>size=</emphasis></simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+       <term><emphasis>veracrypt</emphasis>, <emphasis>tcrypt-veracrypt</emphasis></term>
+    <listitem>
+     <simpara>
+      Use VeraCrypt extension to TrueCrypt device. Only useful in
+      conjunction with <emphasis>tcrypt</emphasis> option (ignored for
+      non-TrueCrypt devices).
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+       <term><emphasis>tcrypthidden</emphasis>, <emphasis>tcrypt-hidden</emphasis></term>
+    <listitem>
+     <simpara>
+       Use hidden TCRYPT header (ignored for non-TCRYPT devices).
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>swap</emphasis></term>
+    <listitem>
+     <simpara>
+      Run <command moreinfo="refentry">mkswap</command> on the created device.
+     </simpara>
+     <simpara>
+      This option is ignored for <emphasis>initramfs</emphasis> devices.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>tmp</emphasis>=&lt;tmpfs&gt;</term>
+    <listitem>
+     <simpara>
+      Run <command moreinfo="refentry">mkfs</command> with filesystem type
+      &lt;tmpfs&gt; on the created device. Default is ext4.
+     </simpara>
+     <simpara>
+      This option is ignored for <emphasis>initramfs</emphasis> devices.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>check</emphasis>=&lt;check&gt;</term>
+    <listitem>
+     <simpara>Check the content of the target device by a suitable program; if
+      the check fails, the device is removed. If a program is provided as an
+      argument, it is run, giving the decrypted volume (target device) as
+      first argument, and the value of the checkargs option as second argument.
+      Cryptdisks/cryptroot searches for the given program in
+      <filename class="directory">/lib/cryptsetup/checks/</filename> first, but
+      full path to program is supported as well.
+     </simpara>
+     <simpara>
+      Default is set in <filename>/etc/default/cryptdisks</filename>
+      (<filename>blkid</filename>).
+     </simpara>
+     <simpara>
+      This option is specific to the Debian <emphasis>crypttab</emphasis>
+      format. It's not supported by <emphasis>systemd</emphasis>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>checkargs</emphasis>=&lt;arguments&gt;</term>
+    <listitem>
+     <simpara>Give &lt;arguments&gt; as the second argument to the check
+      script. See the CHECKSCRIPTS section for more information.
+     </simpara>
+    </listitem>
+     <simpara>
+      This option is specific to the Debian <emphasis>crypttab</emphasis>
+      format. It's not supported by <emphasis>systemd</emphasis>.
+     </simpara>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>initramfs</emphasis></term>
+    <listitem>
+     <simpara>The initramfs hook processes the root device, any resume devices
+      and any devices with the <emphasis>initramfs</emphasis> option set. These
+      devices are processed within the initramfs stage of boot. As an example,
+      that allows the use of remote unlocking using dropbear.
+     </simpara>
+     <simpara>
+      This option is specific to the Debian <emphasis>crypttab</emphasis>
+      format. It's not supported by <emphasis>systemd</emphasis>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>noearly</emphasis></term>
+    <listitem>
+     <simpara>The cryptsetup init scripts are invoked twice during the boot
+      process - once before lvm, raid, etc. are started and once again after
+      that. Sometimes you need to start your encrypted disks in a special
+      order. With this option the device is ignored during the first invocation
+      of the cryptsetup init scripts.
+     </simpara>
+     <simpara>
+      This option is ignored for <emphasis>initramfs</emphasis> devices and
+      specific to the Debian <emphasis>crypttab</emphasis> format. It's not
+      supported by <emphasis>systemd</emphasis>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>noauto</emphasis></term>
+    <listitem>
+     <simpara>Entirely ignore the device at the boot process. It's still
+      possible to map the device manually using cryptdisks_start.
+     </simpara>
+     <simpara>
+      This option is ignored for <emphasis>initramfs</emphasis> devices and
+      specific to the Debian <emphasis>crypttab</emphasis> format. It's not
+      supported by <emphasis>systemd</emphasis>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>loud</emphasis></term>
+    <listitem>
+     <simpara>Be loud. Print warnings if a device does not exist.
+     This option overwrites the option <emphasis>loud</emphasis>.</simpara>
+     <simpara>
+      This option is ignored for <emphasis>initramfs</emphasis> devices and
+      specific to the Debian <emphasis>crypttab</emphasis> format. It's not
+      supported by <emphasis>systemd</emphasis>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>quiet</emphasis></term>
+    <listitem>
+     <simpara>Be quiet. Don't print warnings if a device does not exist.
+     This option overwrites the option <emphasis>loud</emphasis>.</simpara>
+     <simpara>
+      This option is ignored for <emphasis>initramfs</emphasis> devices and
+      specific to the Debian <emphasis>crypttab</emphasis> format. It's not
+      supported by <emphasis>systemd</emphasis>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>keyscript</emphasis>=&lt;path&gt;</term>
+    <listitem>
+     <simpara>
+      The executable at the indicated path is executed with the value of the
+      <emphasis>third field</emphasis> as only argument. The keyscript output
+      is passed to cryptsetup as decyption key.
+      When used in initramfs, the executable either needs to be self-contained
+      (i.e. does'nt rely on any external program which is not present in the
+      initramfs environment) or the dependencies have to added to the initramfs
+      image by other means.
+     </simpara>
+     <simpara>
+      LIMITATIONS: All binaries and files on which the keyscript depends must
+      be available at the time of execution. Special care needs to be taken for
+      encrypted filesystems like /usr or /var. As an example, unlocking
+      encrypted /usr must not depend on binaries from /usr/(s)bin.
+     </simpara>
+     <simpara>
+      This option is specific to the Debian <emphasis>crypttab</emphasis>
+      format. It's not supported by <emphasis>systemd</emphasis>.
+     </simpara>
+     <simpara>
+      WARNING: With systemd as init system, this option might be ignored. At
+      the time this is written (December 2016), the systemd cryptsetup helper
+      doesn't support the keyscript option to /etc/crypttab. For the time
+      being, the only option to use keyscripts along with systemd is to force
+      processing of the corresponding crypto devices in the initramfs. See the
+      'initramfs' option for further information.
+     </simpara>
+     <para>
+      All fields of the appropriate crypttab entry are available to the
+      keyscript as exported environment variables:
+      <variablelist>
+
+       <varlistentry>
+        <term>CRYPTTAB_NAME</term>
+        <listitem><para>
+         The target name
+        </para></listitem>
+       </varlistentry>
+       <varlistentry>
+        <term>CRYPTTAB_SOURCE</term>
+        <listitem><para>
+         The source device
+        </para></listitem>
+       </varlistentry>
+       <varlistentry>
+        <term>CRYPTTAB_KEY</term>
+        <listitem><para>
+         The key file
+        </para></listitem>
+       </varlistentry>
+       <varlistentry>
+        <term>CRYPTTAB_OPTIONS</term>
+        <listitem><para>
+         A list of exported crypttab options
+        </para></listitem>
+       </varlistentry>
+       <varlistentry>
+        <term>CRYPTTAB_OPTION_&lt;option&gt;</term>
+        <listitem><para>
+         The value of the appropriate crypttab option, with value set to 'yes'
+         in case the option is merely a flag.
+         For option aliases, such as 'readonly' and 'read-only', the
+         variable name refers to the first alternative listed (thus
+         'CRYPTTAB_OPTION_readonly' in that case).
+         If the crypttab option name contains '-' characters, then they
+         are replaced with '_' in the exported variable name.  For
+         instance, the value of the 'CRYPTTAB_OPTION_keyfile_offset'
+         environment variable is set to the value of the
+         'keyfile-offset' crypttab option.
+        </para></listitem>
+       </varlistentry>
+       <varlistentry>
+        <term>CRYPTTAB_TRIED</term>
+        <listitem><para>
+         Number of previous tries since start of cryptdisks (counts until
+         maximum number of tries is reached).
+        </para></listitem>
+       </varlistentry>
+
+      </variablelist>
+     </para>
+    </listitem>
+   </varlistentry>
+
+  </variablelist>
+ </refsect1>
+
+ <refsect1 id="crypttab.checkscripts">
+  <title>CHECKSCRIPTS</title>
+  <variablelist>
+
+   <varlistentry>
+    <term><emphasis>blkid</emphasis></term>
+    <listitem>
+     <simpara>Checks for any known filesystem. Supports a filesystem type as
+      argument via &lt;checkargs&gt;:
+     </simpara>
+     <itemizedlist>
+      <listitem><para>
+       no checkargs - succeeds if any valid filesystem is found on the device.
+      </para></listitem>
+      <listitem><para>
+       "none" - succeeds if no valid filesystem is found on the device.
+      </para></listitem>
+      <listitem><para>
+       "ext4" [or another filesystem type like xfs, swap, crypto_LUKS, ...] -
+       succeeds if ext4 filesystem is found on the device.
+      </para></listitem>
+     </itemizedlist>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>un_blkid</emphasis></term>
+    <listitem>
+     <simpara>Checks for no known filesystem. Supports a filesystem type as
+      argument via &lt;checkargs&gt;:
+     </simpara>
+     <itemizedlist>
+      <listitem><para>
+       no checkargs - succeeds if no valid filesystem is found on the device.
+      </para></listitem>
+      <listitem><para>
+       "ext4" [or another filesystem type like xfs, swap, crypto_LUKS, ...] -
+       succeeds if no ext4 filesystem is found on the device.
+      </para></listitem>
+     </itemizedlist>
+    </listitem>
+   </varlistentry>
+
+  </variablelist>
+ </refsect1>
+
+ <refsect1 id="crypttab.examples">
+  <title>EXAMPLES</title>
+  <para>
+   <screen>
+# Encrypted swap device
+cswap /dev/sda6 /dev/urandom cipher=aes-xts-plain64,size=256,hash=sha1,swap
+
+# Encrypted LUKS disk with interactive password, identified by its UUID, discard enabled
+cdisk0 UUID=12345678-9abc-def012345-6789abcdef01 none luks,discard
+
+# Encrypted TCRYPT disk with interactive password, discard enabled
+tdisk0 /dev/sr0 none tcrypt,discard
+
+# Encrypted ext4 disk with interactive password, discard enabled
+# - retry 5 times if the check fails
+cdisk1 /dev/sda2 none discard,cipher=aes-xts-plain64,size=256,hash=sha1,checkargs=ext4,tries=5
+
+# Encrypted disk with interactive password, discard enabled
+# - use a nondefault check script
+# - no retries
+cdisk2 /dev/sdc1 none discard,cipher=aes-xts-plain64,size=256,hash=sha1,check=customscript,tries=1
+
+# Encrypted disk with interactive password, discard enabled
+# - Twofish as the cipher, RIPEMD-160 as the hash
+cdisk3 /dev/sda3 none dscard,cipher=twofish,size=256,hash=ripemd160
+   </screen>
+  </para>
+ </refsect1>
+
+ <refsect1 id="crypttab.environment">
+  <title>ENVIRONMENT</title>
+  <variablelist>
+
+   <varlistentry>
+    <term><emphasis>CRYPTDISKS_ENABLE</emphasis></term>
+    <listitem>
+     <simpara>
+      Set to <emphasis>yes</emphasis> to run cryptdisks initscripts at startup.
+      Set to <emphasis>no</emphasis> to disable cryptdisks initscripts. Default
+      is <emphasis>yes</emphasis>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>CRYPTDISKS_MOUNT</emphasis></term>
+    <listitem>
+     <simpara>Specifies the mountpoints that are mounted before cryptdisks is
+      invoked. Takes mountpoints configured in /etc/fstab as arguments. Separate
+      mountpoints by space.
+      This is useful for keys on removable devices, such as cdrom, usbstick,
+      flashcard, etc. Default is unset.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><emphasis>CRYPTDISKS_CHECK</emphasis></term>
+    <listitem>
+     <simpara>Specifies the default checkscript to be run against the target
+      device, after cryptdisks has been invoked. The target device is passed as
+      the first and only argument to the checkscript. Takes effect if the
+      <emphasis>check</emphasis> option is given in crypttab with no value. See
+      documentation for <emphasis>check</emphasis> option above for more
+      information.
+     </simpara>
+    </listitem>
+   </varlistentry>
+
+  </variablelist>
+ </refsect1>
+
+ <refsect1 id="crypttab.known_upgrade_issues">
+  <title>KNOWN UPGRADE ISSUES</title>
+  <simpara>
+   The upstream defaults for encryption cipher, hash and keysize have changed
+   several times in the past, and they're expected to change again in future,
+   for example if security issues arise.
+
+   On LUKS devices, the used settings are stored in the LUKS header, and thus
+   don't need to be configured in <filename>/etc/crypttab</filename>. For plain
+   dm-crypt devices, no information about used cipher, hash and keysize are
+   available at all.
+
+   Therefore we strongly suggest to configure the cipher, hash and keysize in
+   <filename>/etc/crypttab</filename> for plain dm-crypt devices, even if they
+   match the current default.
+  </simpara>
+ </refsect1>
+
+ <refsect1 id="crypttab.see_also">
+  <title>SEE ALSO</title>
+  <simplelist type="inline">
+   <member><command moreinfo="refentry">cryptsetup</command>(8)</member>
+   <member><command moreinfo="refentry">cryptdisks_start</command>(8)</member>
+   <member><command moreinfo="refentry">cryptdisks_stop</command>(8)</member>
+  </simplelist>
+ </refsect1>
+
+ <refsect1 id="crypttab.author">
+  <title>AUTHOR</title>
+  <simpara>
+   This manual page was originally written by
+   <author>
+    <firstname>Bastian</firstname>
+    <surname>Kleineidam</surname>
+   </author>
+   <email>calvin@debian.org</email>
+   for the Debian distribution of cryptsetup. It has been further improved by
+   <author>
+    <firstname>Michael</firstname>
+    <surname>Gebetsroither</surname>
+   </author>
+   <email>michael.geb@gmx.at</email>,
+   <author>
+    <firstname>David</firstname>
+    <surname>Härdeman</surname>
+   </author>
+   <email>david@hardeman.nu</email>
+   and
+   <author>
+    <firstname>Jonas</firstname>
+    <surname>Meurer</surname>
+   </author>
+   <email>jonas@freesources.org</email>.
+  </simpara>
+ </refsect1>
+
+</refentry>
diff --git a/debian/doc/manpages.xml b/debian/doc/manpages.xml
new file mode 100644
index 0000000..6cd361e
--- /dev/null
+++ b/debian/doc/manpages.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd">
+
+<reference>
+ <title>Manual Pages</title>
+ <xi:include href="cryptdisks_start.xml" xpointer="command.cryptdisks_start" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="cryptdisks_stop.xml" xpointer="command.cryptdisks_stop" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="crypttab.xml" xpointer="file.crypttab" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</reference>
diff --git a/debian/doc/pandoc/encrypted-boot.md b/debian/doc/pandoc/encrypted-boot.md
new file mode 100644
index 0000000..219e6ef
--- /dev/null
+++ b/debian/doc/pandoc/encrypted-boot.md
@@ -0,0 +1,353 @@
+% Full disk encryption, including `/boot`: Unlocking LUKS devices from GRUB
+
+Introduction
+============
+
+So called “full disk encryption” is often a misnomer, because there is
+typically a separate plaintext partition holding `/boot`.  For instance
+the Debian Installer does this in its “encrypted LVM” partitioning method.
+Since not all bootloaders are able to unlock _LUKS_ devices, a plaintext
+`/boot` is the only solution that works for all of them.
+
+Since Jessie GRUB2 has been able to unlock LUKS devices with a new
+[`cryptomount`](https://www.gnu.org/software/grub/manual/grub/html_node/cryptomount.html)
+command, hence enabling encryption of the `/boot` partition as well.
+(As unlocking happens before booting the kernel, that feature is not
+compatible with remote unlocking.)
+
+Enabling unlocking LUKS devices from GRUB [isn't exposed to the d-i
+interface](https://bugs.debian.org/814798) (as of Buster), hence people
+have come up with various custom work-arounds.  But since the Buster
+release [`cryptsetup`(8)] defaults to a new [LUKS header format
+version](https://gitlab.com/cryptsetup/LUKS2-docs), which isn't
+supported by GRUB as of 2.04.
+(There is a [ticket open](https://savannah.gnu.org/bugs/?55093) in
+GRUB's upstream bug tracker.)  _Hence the old custom work-around won't
+work anymore_.  Until LUKS _version 2_ support is added to GRUB2, the
+devices holding `/boot` need to be in _LUKS version 1_ to be unlocked
+from the boot loader.
+
+This document describes a generic way to unlock LUKS devices from GRUB
+for Debian Buster.
+
+
+Encrypting the device holding `/boot`
+=====================================
+
+There are two alternatives here:
+
+  * Either format an existing `/boot` partition to LUKS1; or
+  * Move `/boot` to the root file system.  The root device(s) needs to
+    use LUKS version 1, but existing LUKS2 devices can be converted
+    (in-place) to LUKS1 if desired.
+
+These two alternatives are described in the two following sub-sections.
+
+
+Formatting the existing `/boot` partition to LUKS1
+--------------------------------------------------
+
+Since the installer creates a separate (cleartext) `/boot` partition by
+default in its “encrypted LVM” partitioning method, the simplest solution
+is arguably to re-format it as LUKS1.
+
+That way other partitions, including the one holding the root file
+system, can remain in LUKS2 format and benefit from the stronger
+security guaranties of the newer version: more secure (memory-hard) Key
+Derivation Function, backup header, ability to offload the volume key
+offload to the kernel keyring (thus preventing access from userspace),
+custom sector size, persistent flags, unattended unlocking via kernel
+keyring tokens, etc.
+
+Furthermore every command in this sub-section can be run in the main
+system, no need to run anything from a live CD or an initramfs shell.
+
+Before copying content of the `/boot` directory, remount it read-only to
+make sure data is not modified while it's being copied:
+
+    root@debian:~$ mount -oremount,ro /boot
+
+Then archive the directory elsewhere (on another device), and unmount it
+afterwards:
+
+    root@debian:~$ install -m0600 /dev/null /tmp/boot.tar
+    root@debian:~$ tar -C /boot --acls --xattrs -cf /tmp/boot.tar .
+    root@debian:~$ umount /boot
+
+Optionally, wipe out the underlying block device (assumed to be
+`/dev/sda1` in the rest of this sub-section):
+
+    root@debian:~$ dd if=/dev/urandom of=/dev/sda1 bs=1M
+    dd: error writing '/dev/sda1': No space left on device
+    244+0 records in
+    243+0 records out
+    254803968 bytes (255 MB, 243 MiB) copied, 1.70967 s, 149 MB/s
+
+Format the underlying block device to LUKS1 (note the `--type luks1`
+in the command below, as Buster's [`cryptsetup`(8)] defaults to LUKS2):
+
+    root@debian:~$ cryptsetup luksFormat --type luks1 /dev/sda1
+
+    WARNING!
+    ========
+    This will overwrite data on /dev/sda1 irrevocably.
+
+    Are you sure? (Type uppercase yes): YES
+    Enter passphrase for /dev/sda1:
+    Verify passphrase:
+
+Add a corresponding entry to [`crypttab`(5)] with mapped device name
+`boot_crypt`, and open it afterwards:
+
+    root@debian:~$ uuid="$(blkid -o value -s UUID /dev/sda1)"
+    root@debian:~$ echo "boot_crypt UUID=$uuid none luks" | tee -a /etc/crypttab
+    root@debian:~$ cryptdisks_start boot_crypt
+    Starting crypto disk...boot_crypt (starting)...
+    Please unlock disk boot_crypt:  ********
+    boot_crypt (started)...done.
+
+Now create a file system on the mapped device.  Assuming source device
+for `/boot` is specified by its UUID in the [`fstab`(5)] -- which the
+Debian Installer does by default -- reusing the old UUID avoids editing
+the file.
+
+    root@debian:~$ grep /boot /etc/fstab
+    # /boot was on /dev/sda1 during installation
+    UUID=c104749f-a0fa-406c-9e9a-3fc01f8e2f78 /boot           ext2    defaults        0       2
+    root@debian:~$ mkfs.ext2 -m0 -U c104749f-a0fa-406c-9e9a-3fc01f8e2f78 /dev/mapper/boot_crypt
+    mke2fs 1.44.5 (15-Dec-2018)
+    Creating filesystem with 246784 1k blocks and 61752 inodes
+    Filesystem UUID: c104749f-a0fa-406c-9e9a-3fc01f8e2f78
+    […]
+
+Finally, mount `/boot` again from [`fstab`(5)], and copy the saved tarball
+to the new (and now encrypted) file system.
+
+    root@debian:~$ mount -v /boot
+    mount: /dev/mapper/boot_crypt mounted on /boot.
+    root@debian:~$ tar -C /boot -xf /tmp/boot.tar
+
+You can skip the next sub-section and go directly to [Enabling
+`cryptomount` in GRUB2].
+
+
+Moving `/boot` to the root file system
+--------------------------------------
+
+The [above sub-section][Formatting the existing `/boot` partition to LUKS1]
+described how to to re-format the `/boot` partition as LUKS1.
+Alternatively, it can be moved to the root file system, assuming the
+latter is not held by any LUKS2 device.  (As shown below, LUKS2 devices
+created with default parameters can be “downgraded” to LUKS1.)
+
+The advantage of this method is that the original `/boot` partition can
+be preserved and used in case of disaster recovery (if for some reason
+the GRUB image is lacking the `cryptodisk` module and the original
+plaintext `/boot` partition is lost, you'd need to boot from a live CD
+to recover).  Moreover increasing the number of partitions increases
+usage pattern visibility: a separate `/boot` partitions, although
+encrypted, will likely leak the fact that a kernel update took place to
+an attacker with access to pre- and post-update snapshots.
+
+On the other hand, the inconvenient of that method is that the root file
+system can't benefit from the nice LUKS2 improvements over LUKS1, as
+listed above.  Another minor inconvenient is that space that was
+occupied by the former `/boot` partition becomes unused and can't easily
+be reclaimed by the root file system.
+
+### Downgrading LUKS2 to LUKS1 ###
+
+Check the LUKS format version on the root device (assumed to be
+`/dev/sda3` in the rest of this sub-section):
+
+    root@debian:~$ cryptsetup luksDump /dev/sda3 | grep -A1 "^LUKS"
+    LUKS header information
+    Version:        2
+
+Here the LUKS format version is 2, so the device needs to be converted
+to LUKS _version 1_ to be able to unlock from GRUB.  Unlike the remaining
+of this document, the conversion can't be done on an open device, so
+you'll need to use a live CD, or append `break` to the kernel
+command-line to break to an initramfs shell.
+
+Run `cryptsetup convert --type luks1 DEVICE` to downgrade.  However if
+the device was created with the default parameters the in-place
+conversion will fail:
+
+    root@debian:~$ cryptsetup convert --type luks1 /dev/sda3
+
+    WARNING!
+    ========
+    This operation will convert /dev/sda3 to LUKS1 format.
+
+
+    Are you sure? (Type uppercase yes): YES
+    Cannot convert to LUKS1 format - keyslot 0 is not LUKS1 compatible.
+
+This is because its first key slot uses Argon2 as Password-Based Key
+Derivation Function (PBKDF) algorithm:
+
+    root@debian:~$ cryptsetup luksDump /dev/sda3 | grep PBKDF:
+            PBKDF:      argon2i
+
+Argon2 is a memory-hard function that was selected as the winner of the
+Password-Hashing Competition; LUKS2 devices use it by default, but
+LUKS1's only supported PBKDF algorithm is PKBDF2.  Hence the key slot
+has to be converted to PKBDF2 prior to LUKS format version downgrade.
+
+    root@debian:~$ cryptsetup luksChangeKey --key-slot 0 --pbkdf pbkdf2 /dev/sda3
+    Enter passphrase to be changed:
+    Enter new passphrase:
+    Verify passphrase:
+
+(You can reuse the existing passphrase in the above prompts.)  Now that
+all keyslots use the PBKDF2 algorithm, the device shouldn't have any
+remaining LUKS2-only features, and can be converted to LUKS1.
+
+    root@debian:~$ cryptsetup luksDump /dev/sda3 | grep PBKDF:
+            PBKDF:      pbkdf2
+    root@debian:~$ cryptsetup convert --type luks1 /dev/sda3
+
+    WARNING!
+    ========
+    This operation will convert /dev/sda3 to LUKS1 format.
+
+
+    Are you sure? (Type uppercase yes): YES
+    root@debian:~$ cryptsetup luksDump /dev/sda3 | grep -A1 ^LUKS
+    LUKS header information
+
+### Moving `/boot` to the root file system ###
+
+(The moving itself can be done from the normal system, no need to use a
+live CD or an initramfs shell.)
+
+To ensure data is not modified while it's being copied, remount `/boot`
+read-only:
+
+    root@debian:~$ mount -oremount,ro /boot
+
+Then recursively copy the directory to the root file system, and replace
+the old `/boot` mountpoint with the new directory.
+
+    root@debian:~$ cp -aT /boot /boot.tmp
+    root@debian:~$ umount /boot
+    root@debian:~$ rmdir /boot
+    root@debian:~$ mv -T /boot.tmp /boot
+
+Comment out the fstab(5) entry for the `/boot` mountpoint, otherwise
+at reboot `init`(1) will mount it hence shadow data in the new `/boot`
+directory with data from the plaintext partition.
+
+    root@debian:~$ grep /boot /etc/fstab
+    ## /boot was on /dev/sda1 during installation
+    #UUID=c104749f-a0fa-406c-9e9a-3fc01f8e2f78 /boot           ext2    defaults        0       2
+
+
+Enabling `cryptomount` in GRUB2
+===============================
+
+Enable the feature and update the GRUB image:
+
+    root@debian:~$ echo "GRUB_ENABLE_CRYPTODISK=y" >>/etc/default/grub
+    root@debian:~$ echo "GRUB_PRELOAD_MODULES=\"luks cryptodisk\"" >>/etc/default/grub
+    root@debian:~$ update-grub
+    root@debian:~$ grub-install /dev/sda
+
+If everything went well, `/boot/grub/grub.cfg` should contain `insmod
+cryptodisk` (and also `insmod lvm` if `/boot` is on a Logical Volume).
+
+
+Avoiding the extra password prompt
+==================================
+
+The device holding the kernel (and the initramfs image) is unlocked by
+GRUB, but the root device needs to be unlocked again at initramfs stage,
+regardless whether it's the same device or not.  This is because GRUB
+boots with the given `vmlinuz` and initramfs images, but there currently
+is no way to securely pass cryptographic material (or Device Mapper
+information) to the kernel.  Hence the Device Mapper table is initially
+empty at initramfs stage; in other words, all devices are locked, and
+the root device needs to be unlocked again.
+
+To avoid extra passphrase prompts at initramfs stage, a work around is
+to unlock via key files stored into the initramfs image.  Since the
+initramfs image itself now resides on an encrypted device, this still
+provides protection for data at rest.  With LUKS1 the volume key can
+already be found by userspace in the Device Mapper table, so including
+key files to the initramfs image -- created with restrictive permissions --
+doesn't change the threat model.  (However for LUKS2 the volume key is
+offloaded to the kernel keyring by default, thus no longer accessible to
+userspace, and having keyfiles readable by root slightly changes the
+threat model.)
+
+To enable unlocking via key files for the root file system, first
+generate the shared secret (here with 512 bits of entropy as it's also
+the size of the volume key) inside a new file:
+
+    root@debian:~$ mkdir -m0700 /etc/keys
+    root@debian:~$ ( umask 0077 && dd if=/dev/urandom bs=1 count=64 of=/etc/keys/root.key )
+    64+0 records in
+    64+0 records out
+    64 bytes copied, 0.000698363 s, 91.6 kB/s
+
+Now create a new key slot with that key file:
+
+    root@debian:~$ cryptsetup luksAddKey /dev/sda3 /etc/keys/root.key
+    Enter any existing passphrase:
+
+    root@debian:~$ cryptsetup luksDump /dev/sda3 | grep "^Key Slot"
+    Key Slot 0: ENABLED
+    Key Slot 1: ENABLED
+    Key Slot 2: DISABLED
+    Key Slot 3: DISABLED
+    Key Slot 4: DISABLED
+    Key Slot 5: DISABLED
+    Key Slot 6: DISABLED
+    Key Slot 7: DISABLED
+
+Edit the [`crypttab`(5)] and set the third column to the key file path for
+the root device entry:
+
+    root@debian:~$ cat /etc/crypttab
+    root_crypt UUID=… /etc/keys/root.key luks,discard,key-slot=1
+
+(The unlock logic normally runs the PBKDF algorithm through each keyslot
+sequentially until a match is found.  Since the key file is explicitly
+targeting the second key slot, its index can be specified with
+`key-slot=1` in the [`crypttab`(5)] to save some expensive PBKDF
+computations and reduce boot time.)
+
+In `/etc/cryptsetup-initramfs/conf-hook`, set `KEYFILE_PATTERN` to a
+`glob`(7) expanding to the key files to include to the initramfs image.
+
+    root@debian:~$ echo "KEYFILE_PATTERN=\"/etc/keys/*.key\"" >>/etc/cryptsetup-initramfs/conf-hook
+
+In `/etc/initramfs-tools/initramfs.conf`, set `UMASK` to a restrictive
+value to avoid leaking key material.  See [`initramfs.conf`(5)] for
+details.
+
+    root@debian:~$ echo UMASK=0077 >>/etc/initramfs-tools/initramfs.conf
+
+Finally re-generate the initramfs image, and double-check that it has
+restrictive permissions and includes the key.
+
+    root@debian:~$ update-initramfs -u
+    update-initramfs: Generating /boot/initrd.img-4.19.0-4-amd64
+    root@debian:~$ stat -L -c "%A  %n" /initrd.img
+    -rw-------  /initrd.img
+    root@debian:~$ lsinitramfs /initrd.img | grep "^cryptroot/keyfiles/"
+    cryptroot/keyfiles/root_crypt.key
+
+(`cryptsetup-initramfs` normalises and renames key files inside the
+initramfs, hence the new keyfile name.)
+
+Should be safe to reboot now :-)  If all went well you should see a
+single passphrase prompt.
+
+[`cryptsetup`(8)]: https://manpages.debian.org/cryptsetup.8.en.html
+[`crypttab`(5)]: https://manpages.debian.org/crypttab.5.en.html
+[`fstab`(5)]: https://manpages.debian.org/fstab.5.en.html
+[`initramfs.conf`(5)]: https://manpages.debian.org/initramfs.conf.5.en.html
+
+ -- Guilhem Moulin <guilhem@debian.org>, Mon, 09 Jun 2019 16:35:20 +0200
diff --git a/debian/doc/pandoc/index.md b/debian/doc/pandoc/index.md
new file mode 100644
index 0000000..bd750c4
--- /dev/null
+++ b/debian/doc/pandoc/index.md
@@ -0,0 +1,24 @@
+Cryptsetup for Debian
+=====================
+
+The main documentation:
+
+* [Debian Cryptsetup README](README.Debian.html)
+* [Debian Cryptsetup Debugging README](README.debug.html)
+* [Cryptsetup Initramfs intregration README](README.initramfs.html)
+
+Detailed documentation of specific setups:
+
+* [Debian encrypted boot documentation](encrypted-boot.html)
+
+Documentation of some particular keyscripts:
+
+* [Cryptsetup GnuPG keyscript README](README.gnupg.html)
+* [Cryptsetup GnuPG smartcard keyscript README](README.gnupg-sc.html)
+* [Cryptsetup keyctl keyscript README](README.keyctl.html)
+* [Cryptsetup smartcard keyscript README](README.opensc.html)
+
+
+**Please note**: Some of the documentation might be outdated. We
+recommend to look at the date of the page footer. It gives an idea
+about when the docs last got written and/or updated.
diff --git a/debian/doc/pandoc/pandoc.css b/debian/doc/pandoc/pandoc.css
new file mode 100644
index 0000000..b2289e7
--- /dev/null
+++ b/debian/doc/pandoc/pandoc.css
@@ -0,0 +1,74 @@
+body {
+    margin: auto;
+    padding-right: 1em;
+    padding-left: 1em;
+    margin-left: 2em;
+    border-left: 1px solid black;
+    color: black;
+    font-size: 100%;
+    line-height: 140%;
+    color: #333;
+}
+
+pre {
+    border: 1px dotted gray;
+    background-color: #ececec;
+    color: #1111111;
+    padding: 0.5em;
+}
+
+code {
+    font-family: monospace;
+}
+
+h1 a, h2 a, h3 a, h4 a, h5 a {
+    text-decoration: none;
+    color: #7a5ada;
+}
+h1, h2, h3, h4, h5 {
+    font-family: sans-serif;
+    font-weight: bold;
+    text-decoration: underline;
+    color: #7a5ada;
+}
+h1 {
+    font-size: 130%;
+}
+h2 {
+    font-size: 110%;
+}
+h3 {
+    font-size: 95%;
+}
+h4 {
+    font-size: 90%;
+    font-style: italic;
+}
+h5 {
+    font-size: 90%;
+    font-style: italic;
+}
+h1.title {
+    font-size: 200%;
+    font-weight: bold;
+    padding-top: 0.2em;
+    padding-bottom: 0.2em;
+    text-align: left;
+    border: none;
+}
+
+dt code {
+    font-weight: bold;
+}
+dd p {
+    margin-top: 0;
+}
+
+#TOC {
+    float: right;
+    width: 40%;
+    background: #eee;
+    font-size: 0.8em;
+    padding: 1em 2em;
+    margin: 0.0 0.5em 0.5em;
+}
diff --git a/debian/doc/variables.xml.in b/debian/doc/variables.xml.in
new file mode 100644
index 0000000..8ca89f2
--- /dev/null
+++ b/debian/doc/variables.xml.in
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd">
+
+<refentry>
+
+ <refmeta>
+  <refmiscinfo class="version">VERSION</refmiscinfo>
+  <refmiscinfo class="source">cryptsetup</refmiscinfo>
+  <refmiscinfo class="manual">cryptsetup manual</refmiscinfo>
+ </refmeta>
+
+ <refentryinfo>
+  <date>DATE</date>
+ </refentryinfo>
+
+</refentry>