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