3 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
4 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
5 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"systemd-cryptsetup-generator" conditional='HAVE_LIBCRYPTSETUP'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>systemd-cryptsetup-generator
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>systemd-cryptsetup-generator
</refentrytitle>
16 <manvolnum>8</manvolnum>
20 <refname>systemd-cryptsetup-generator
</refname>
21 <refpurpose>Unit generator for
<filename>/etc/crypttab
</filename></refpurpose>
25 <para><filename>/usr/lib/systemd/system-generators/systemd-cryptsetup-generator
</filename></para>
29 <title>Description
</title>
31 <para><filename>systemd-cryptsetup-generator
</filename> is a
32 generator that translates
<filename>/etc/crypttab
</filename> into
33 native systemd units early at boot and when configuration of the
34 system manager is reloaded. This will create
35 <citerefentry><refentrytitle>systemd-cryptsetup@.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
36 units as necessary.
</para>
38 <para><filename>systemd-cryptsetup-generator
</filename> implements
39 <citerefentry><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
43 <title>Kernel Command Line
</title>
45 <para><filename>systemd-cryptsetup-generator
</filename>
46 understands the following kernel command line parameters:
</para>
48 <variablelist class='kernel-commandline-options'
>
50 <term><varname>luks=
</varname></term>
51 <term><varname>rd.luks=
</varname></term>
53 <listitem><para>Takes a boolean argument. Defaults to
<literal>yes
</literal>. If
54 <literal>no
</literal>, disables the generator entirely.
<varname>rd.luks=
</varname> is honored only
55 in the initrd while
<varname>luks=
</varname> is honored by both the main system and in the initrd.
58 <xi:include href=
"version-info.xml" xpointer=
"v186"/></listitem>
62 <term><varname>luks.crypttab=
</varname></term>
63 <term><varname>rd.luks.crypttab=
</varname></term>
65 <listitem><para>Takes a boolean argument. Defaults to
<literal>yes
</literal>. If
66 <literal>no
</literal>, causes the generator to ignore any devices configured in
67 <filename>/etc/crypttab
</filename> (
<varname>luks.uuid=
</varname> will still work however).
68 <varname>rd.luks.crypttab=
</varname> is honored only in initrd while
69 <varname>luks.crypttab=
</varname> is honored by both the main system and in the initrd.
72 <xi:include href=
"version-info.xml" xpointer=
"v186"/></listitem>
76 <term><varname>luks.uuid=
</varname></term>
77 <term><varname>rd.luks.uuid=
</varname></term>
79 <listitem><para>Takes a LUKS superblock UUID as argument. This will activate the specified device as
80 part of the boot process as if it was listed in
<filename>/etc/crypttab
</filename>. This option may
81 be specified more than once in order to set up multiple devices.
<varname>rd.luks.uuid=
</varname> is
82 honored only in the initrd, while
<varname>luks.uuid=
</varname> is honored by both the main system
83 and in the initrd.
</para>
85 <para>If
<filename>/etc/crypttab
</filename> contains entries with the same UUID, then the name,
86 keyfile and options specified there will be used. Otherwise, the device will have the name
87 <literal>luks-UUID
</literal>.
</para>
89 <para>If
<filename>/etc/crypttab
</filename> exists, only those UUIDs specified on the kernel command
90 line will be activated in the initrd or the real root.
</para>
92 <xi:include href=
"version-info.xml" xpointer=
"v186"/>
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>This parameter is the analogue of the first
<citerefentry><refentrytitle>crypttab
</refentrytitle>
108 <manvolnum>5</manvolnum></citerefentry> field
<replaceable>volume-name
</replaceable>.
</para>
110 <para><varname>rd.luks.name=
</varname> is honored only in the initrd, while
111 <varname>luks.name=
</varname> is honored by both the main system and in the initrd.
</para>
113 <xi:include href=
"version-info.xml" xpointer=
"v218"/>
118 <term><varname>luks.data=
</varname></term>
119 <term><varname>rd.luks.data=
</varname></term>
121 <listitem><para>Takes a LUKS super block UUID followed by a
<literal>=
</literal> and a block device
122 specification for device hosting encrypted data.
</para>
124 <para>For those entries specified with
<varname>rd.luks.uuid=
</varname> or
125 <varname>luks.uuid=
</varname>, the data device will be set to the one specified by
126 <varname>rd.luks.data=
</varname> or
<varname>luks.data=
</varname> of the corresponding UUID.
</para>
128 <para>LUKS data device parameter is useful for specifying encrypted data devices with detached headers specified in
129 <varname>luks.options
</varname> entry containing
<literal>header=
</literal> argument. For example,
130 <varname>rd.luks.uuid=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40
131 <varname>rd.luks.options=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40=header=/path/to/luks.hdr
132 <varname>rd.luks.data=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40=/dev/sdx.
133 Hence, in this case, we will attempt to unlock LUKS device assembled from data device
<literal>/dev/sdx
</literal>
134 and LUKS header (metadata) put in
<literal>/path/to/luks.hdr
</literal> file. This syntax is for now
135 only supported on a per-device basis, i.e. you have to specify LUKS device UUID.
</para>
137 <para>This parameter is the analogue of the second
<citerefentry><refentrytitle>crypttab
</refentrytitle>
138 <manvolnum>5</manvolnum></citerefentry> field
<replaceable>encrypted-device
</replaceable>.
</para>
140 <para><varname>rd.luks.data=
</varname> is honored only in the initrd, while
141 <varname>luks.data=
</varname> is honored by both the main system and in the initrd.
</para>
143 <xi:include href=
"version-info.xml" xpointer=
"v247"/>
148 <term><varname>luks.key=
</varname></term>
149 <term><varname>rd.luks.key=
</varname></term>
151 <listitem><para>Takes a password file name as argument or a
152 LUKS super block UUID followed by a
<literal>=
</literal> and a
153 password file name.
</para>
155 <para>For those entries specified with
156 <varname>rd.luks.uuid=
</varname> or
157 <varname>luks.uuid=
</varname>, the password file will be set
158 to the one specified by
<varname>rd.luks.key=
</varname> or
159 <varname>luks.key=
</varname> of the corresponding UUID, or the
160 password file that was specified without a UUID.
</para>
162 <para>It is also possible to specify an external device which
163 should be mounted before we attempt to unlock the LUKS device.
164 systemd-cryptsetup will use password file stored on that
165 device. Device containing password file is specified by
166 appending colon and a device identifier to the password file
168 <varname>rd.luks.uuid=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40
169 <varname>rd.luks.key=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40=/keyfile:LABEL=keydev.
170 Hence, in this case, we will attempt to mount file system
171 residing on the block device with label
<literal>keydev
</literal>.
172 This syntax is for now only supported on a per-device basis,
173 i.e. you have to specify LUKS device UUID.
</para>
175 <para>This parameter is the analogue of the third
<citerefentry><refentrytitle>crypttab
</refentrytitle>
176 <manvolnum>5</manvolnum></citerefentry> field
<replaceable>key-file
</replaceable>.
</para>
178 <para><varname>rd.luks.key=
</varname> is honored only in the initrd, while
179 <varname>luks.key=
</varname> is honored by both the main system and in the initrd.
</para>
181 <xi:include href=
"version-info.xml" xpointer=
"v202"/>
186 <term><varname>luks.options=
</varname></term>
187 <term><varname>rd.luks.options=
</varname></term>
189 <listitem><para>Takes a LUKS super block UUID followed by an
190 <literal>=
</literal> and a string of options separated by
191 commas as argument. This will override the options for the
193 <para>If only a list of options, without a UUID, is
194 specified, they apply to any UUIDs not specified elsewhere,
195 and without an entry in
196 <filename>/etc/crypttab
</filename>.
</para>
198 <para>This parameter is the analogue of the fourth
<citerefentry><refentrytitle>crypttab
</refentrytitle>
199 <manvolnum>5</manvolnum></citerefentry> field
<replaceable>options
</replaceable>.
</para>
201 <para>It is possible to specify an external device which
202 should be mounted before we attempt to unlock the LUKS device.
203 systemd-cryptsetup will assemble LUKS device by combining
204 data device specified in
<varname>luks.data
</varname> with
205 detached LUKS header found in
<literal>header=
</literal>
206 argument. For example,
207 <varname>rd.luks.uuid=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40
208 <varname>rd.luks.options=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40=header=/luks.hdr:LABEL=hdrdev
209 <varname>rd.luks.data=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40=/dev/sdx.
210 Hence, in this case, we will attempt to mount file system
211 residing on the block device with label
<literal>hdrdev
</literal>, and look
212 for
<literal>luks.hdr
</literal> on that file system. Said header will be used
213 to unlock (decrypt) encrypted data stored on /dev/sdx.
214 This syntax is for now only supported on a per-device basis,
215 i.e. you have to specify LUKS device UUID.
</para>
217 <para><varname>rd.luks.options=
</varname> is honored only by initial
218 RAM disk (initrd) while
<varname>luks.options=
</varname> is
219 honored by both the main system and in the initrd.
</para>
221 <xi:include href=
"version-info.xml" xpointer=
"v208"/>
228 <title>See Also
</title>
229 <para><simplelist type=
"inline">
230 <member><citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
231 <member><citerefentry><refentrytitle>crypttab
</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
232 <member><citerefentry><refentrytitle>systemd-cryptsetup@.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
233 <member><citerefentry><refentrytitle>systemd-cryptenroll
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
234 <member><citerefentry project='die-net'
><refentrytitle>cryptsetup
</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
235 <member><citerefentry><refentrytitle>systemd-fstab-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>