man/systemd-cryptsetup-generator.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   6 <refentry id="systemd-cryptsetup-generator" conditional='HAVE_LIBCRYPTSETUP'>
   7
   8   <refentryinfo>
   9     <title>systemd-cryptsetup-generator</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd-cryptsetup-generator</refentrytitle>
  15     <manvolnum>8</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd-cryptsetup-generator</refname>
  20     <refpurpose>Unit generator for <filename>/etc/crypttab</filename></refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <para><filename>/usr/lib/systemd/system-generators/systemd-cryptsetup-generator</filename></para>
  25   </refsynopsisdiv>
  26
  27   <refsect1>
  28     <title>Description</title>
  29
  30     <para><filename>systemd-cryptsetup-generator</filename> is a
  31     generator that translates <filename>/etc/crypttab</filename> into
  32     native systemd units early at boot and when configuration of the
  33     system manager is reloaded. This will create
  34     <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  35     units as necessary.</para>
  36
  37     <para><filename>systemd-cryptsetup-generator</filename> implements
  38     <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
  39   </refsect1>
  40
  41   <refsect1>
  42     <title>Kernel Command Line</title>
  43
  44     <para><filename>systemd-cryptsetup-generator</filename>
  45     understands the following kernel command line parameters:</para>
  46
  47     <variablelist class='kernel-commandline-options'>
  48       <varlistentry>
  49         <term><varname>luks=</varname></term>
  50         <term><varname>rd.luks=</varname></term>
  51
  52         <listitem><para>Takes a boolean argument. Defaults to
  53         <literal>yes</literal>. If <literal>no</literal>, disables the
  54         generator entirely. <varname>rd.luks=</varname> is honored
  55         only by initial RAM disk (initrd) while
  56         <varname>luks=</varname> is honored by both the main system
  57         and the initrd. </para></listitem>
  58       </varlistentry>
  59
  60       <varlistentry>
  61         <term><varname>luks.crypttab=</varname></term>
  62         <term><varname>rd.luks.crypttab=</varname></term>
  63
  64         <listitem><para>Takes a boolean argument. Defaults to
  65         <literal>yes</literal>. If <literal>no</literal>, causes the
  66         generator to ignore any devices configured in
  67         <filename>/etc/crypttab</filename>
  68         (<varname>luks.uuid=</varname> will still work however).
  69         <varname>rd.luks.crypttab=</varname> is honored only by
  70         initial RAM disk (initrd) while
  71         <varname>luks.crypttab=</varname> is honored by both the main
  72         system and the initrd. </para></listitem>
  73       </varlistentry>
  74
  75       <varlistentry>
  76         <term><varname>luks.uuid=</varname></term>
  77         <term><varname>rd.luks.uuid=</varname></term>
  78
  79         <listitem><para>Takes a LUKS superblock UUID as argument. This
  80         will activate the specified device as part of the boot process
  81         as if it was listed in <filename>/etc/crypttab</filename>.
  82         This option may be specified more than once in order to set up
  83         multiple devices. <varname>rd.luks.uuid=</varname> is honored
  84         only by initial RAM disk (initrd) while
  85         <varname>luks.uuid=</varname> is honored by both the main
  86         system and the initrd.</para>
  87         <para>If /etc/crypttab contains entries with the same UUID,
  88         then the name, keyfile and options specified there will be
  89         used. Otherwise, the device will have the name
  90         <literal>luks-UUID</literal>.</para>
  91         <para>If /etc/crypttab exists, only those UUIDs
  92         specified on the kernel command line
  93         will be activated in the initrd or the real root.</para>
  94         </listitem>
  95       </varlistentry>
  96
  97       <varlistentry>
  98         <term><varname>luks.name=</varname></term>
  99         <term><varname>rd.luks.name=</varname></term>
 100
 101         <listitem><para>Takes a LUKS super block UUID followed by an
 102         <literal>=</literal> and a name. This implies
 103         <varname>rd.luks.uuid=</varname> or
 104         <varname>luks.uuid=</varname> and will additionally make the
 105         LUKS device given by the UUID appear under the provided
 106         name.</para>
 107
 108         <para><varname>rd.luks.name=</varname> is honored only by
 109         initial RAM disk (initrd) while <varname>luks.name=</varname>
 110         is honored by both the main system and the initrd.</para>
 111         </listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><varname>luks.options=</varname></term>
 116         <term><varname>rd.luks.options=</varname></term>
 117
 118         <listitem><para>Takes a LUKS super block UUID followed by an
 119         <literal>=</literal> and a string of options separated by
 120         commas as argument. This will override the options for the
 121         given UUID.</para>
 122         <para>If only a list of options, without an UUID, is
 123         specified, they apply to any UUIDs not specified elsewhere,
 124         and without an entry in
 125         <filename>/etc/crypttab</filename>.</para><para>
 126         <varname>rd.luks.options=</varname> is honored only by initial
 127         RAM disk (initrd) while <varname>luks.options=</varname> is
 128         honored by both the main system and the initrd.</para>
 129         </listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><varname>luks.key=</varname></term>
 134         <term><varname>rd.luks.key=</varname></term>
 135
 136         <listitem><para>Takes a password file name as argument or a
 137         LUKS super block UUID followed by a <literal>=</literal> and a
 138         password file name.</para>
 139
 140         <para>For those entries specified with
 141         <varname>rd.luks.uuid=</varname> or
 142         <varname>luks.uuid=</varname>, the password file will be set
 143         to the one specified by <varname>rd.luks.key=</varname> or
 144         <varname>luks.key=</varname> of the corresponding UUID, or the
 145         password file that was specified without a UUID.</para>
 146
 147         <para>It is also possible to specify an external device which
 148         should be mounted before we attempt to unlock the LUKS device.
 149         systemd-cryptsetup will use password file stored on that
 150         device. Device containing password file is specified by
 151         appending colon and a device identifier to the password file
 152         path. For example,
 153         <varname>rd.luks.uuid=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40
 154         <varname>rd.luks.key=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40=/keyfile:LABEL=keydev.
 155         Hence, in this case, we will attempt to mount file system
 156         residing on the block device with label <literal>keydev</literal>.
 157         This syntax is for now only supported on a per-device basis,
 158         i.e. you have to specify LUKS device UUID.</para>
 159
 160         <para><varname>rd.luks.key=</varname>
 161         is honored only by initial RAM disk
 162         (initrd) while
 163         <varname>luks.key=</varname> is
 164         honored by both the main system and
 165         the initrd.</para>
 166         </listitem>
 167       </varlistentry>
 168     </variablelist>
 169   </refsect1>
 170
 171   <refsect1>
 172     <title>See Also</title>
 173     <para>
 174       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 177       <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 179     </para>
 180   </refsect1>
 181
 182 </refentry>