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-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.
60 <term><varname>luks.crypttab=
</varname></term>
61 <term><varname>rd.luks.crypttab=
</varname></term>
63 <listitem><para>Takes a boolean argument. Defaults to
<literal>yes
</literal>. If
64 <literal>no
</literal>, causes the generator to ignore any devices configured in
65 <filename>/etc/crypttab
</filename> (
<varname>luks.uuid=
</varname> will still work however).
66 <varname>rd.luks.crypttab=
</varname> is honored only in initrd while
67 <varname>luks.crypttab=
</varname> is honored by both the main system and in the initrd.
72 <term><varname>luks.uuid=
</varname></term>
73 <term><varname>rd.luks.uuid=
</varname></term>
75 <listitem><para>Takes a LUKS superblock UUID as argument. This will activate the specified device as
76 part of the boot process as if it was listed in
<filename>/etc/crypttab
</filename>. This option may
77 be specified more than once in order to set up multiple devices.
<varname>rd.luks.uuid=
</varname> is
78 honored only in the initrd, while
<varname>luks.uuid=
</varname> is honored by both the main system
79 and in the initrd.
</para>
81 <para>If
<filename>/etc/crypttab
</filename> contains entries with the same UUID, then the name,
82 keyfile and options specified there will be used. Otherwise, the device will have the name
83 <literal>luks-UUID
</literal>.
</para>
85 <para>If
<filename>/etc/crypttab
</filename> exists, only those UUIDs specified on the kernel command
86 line will be activated in the initrd or the real root.
</para>
91 <term><varname>luks.name=
</varname></term>
92 <term><varname>rd.luks.name=
</varname></term>
94 <listitem><para>Takes a LUKS super block UUID followed by an
95 <literal>=
</literal> and a name. This implies
96 <varname>rd.luks.uuid=
</varname> or
97 <varname>luks.uuid=
</varname> and will additionally make the
98 LUKS device given by the UUID appear under the provided
101 <para>This parameter is the analogue of the first
<citerefentry><refentrytitle>crypttab
</refentrytitle>
102 <manvolnum>5</manvolnum></citerefentry> field
<replaceable>volume-name
</replaceable>.
</para>
104 <para><varname>rd.luks.name=
</varname> is honored only in the initrd, while
105 <varname>luks.name=
</varname> is honored by both the main system and in the initrd.
</para>
110 <term><varname>luks.data=
</varname></term>
111 <term><varname>rd.luks.data=
</varname></term>
113 <listitem><para>Takes a LUKS super block UUID followed by a
<literal>=
</literal> and a block device
114 specification for device hosting encrypted data.
</para>
116 <para>For those entries specified with
<varname>rd.luks.uuid=
</varname> or
117 <varname>luks.uuid=
</varname>, the data device will be set to the one specified by
118 <varname>rd.luks.data=
</varname> or
<varname>luks.data=
</varname> of the corresponding UUID.
</para>
120 <para>LUKS data device parameter is useful for specifying encrypted data devices with detached headers specified in
121 <varname>luks.options
</varname> entry containing
<literal>header=
</literal> argument. For example,
122 <varname>rd.luks.uuid=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40
123 <varname>rd.luks.options=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40=header=/path/to/luks.hdr
124 <varname>rd.luks.data=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40=/dev/sdx.
125 Hence, in this case, we will attempt to unlock LUKS device assembled from data device
<literal>/dev/sdx
</literal>
126 and LUKS header (metadata) put in
<literal>/path/to/luks.hdr
</literal> file. This syntax is for now
127 only supported on a per-device basis, i.e. you have to specify LUKS device UUID.
</para>
129 <para>This parameter is the analogue of the second
<citerefentry><refentrytitle>crypttab
</refentrytitle>
130 <manvolnum>5</manvolnum></citerefentry> field
<replaceable>encrypted-device
</replaceable>.
</para>
132 <para><varname>rd.luks.data=
</varname> is honored only in the initrd, while
133 <varname>luks.data=
</varname> is honored by both the main system and in the initrd.
</para>
138 <term><varname>luks.key=
</varname></term>
139 <term><varname>rd.luks.key=
</varname></term>
141 <listitem><para>Takes a password file name as argument or a
142 LUKS super block UUID followed by a
<literal>=
</literal> and a
143 password file name.
</para>
145 <para>For those entries specified with
146 <varname>rd.luks.uuid=
</varname> or
147 <varname>luks.uuid=
</varname>, the password file will be set
148 to the one specified by
<varname>rd.luks.key=
</varname> or
149 <varname>luks.key=
</varname> of the corresponding UUID, or the
150 password file that was specified without a UUID.
</para>
152 <para>It is also possible to specify an external device which
153 should be mounted before we attempt to unlock the LUKS device.
154 systemd-cryptsetup will use password file stored on that
155 device. Device containing password file is specified by
156 appending colon and a device identifier to the password file
158 <varname>rd.luks.uuid=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40
159 <varname>rd.luks.key=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40=/keyfile:LABEL=keydev.
160 Hence, in this case, we will attempt to mount file system
161 residing on the block device with label
<literal>keydev
</literal>.
162 This syntax is for now only supported on a per-device basis,
163 i.e. you have to specify LUKS device UUID.
</para>
165 <para>This parameter is the analogue of the third
<citerefentry><refentrytitle>crypttab
</refentrytitle>
166 <manvolnum>5</manvolnum></citerefentry> field
<replaceable>key-file
</replaceable>.
</para>
168 <para><varname>rd.luks.key=
</varname> is honored only in the initrd, while
169 <varname>luks.key=
</varname> is honored by both the main system and in the initrd.
</para>
174 <term><varname>luks.options=
</varname></term>
175 <term><varname>rd.luks.options=
</varname></term>
177 <listitem><para>Takes a LUKS super block UUID followed by an
178 <literal>=
</literal> and a string of options separated by
179 commas as argument. This will override the options for the
181 <para>If only a list of options, without a UUID, is
182 specified, they apply to any UUIDs not specified elsewhere,
183 and without an entry in
184 <filename>/etc/crypttab
</filename>.
</para>
186 <para>This parameter is the analogue of the fourth
<citerefentry><refentrytitle>crypttab
</refentrytitle>
187 <manvolnum>5</manvolnum></citerefentry> field
<replaceable>options
</replaceable>.
</para>
189 <para>It is possible to specify an external device which
190 should be mounted before we attempt to unlock the LUKS device.
191 systemd-cryptsetup will assemble LUKS device by combining
192 data device specified in
<varname>luks.data
</varname> with
193 detached LUKS header found in
<literal>header=
</literal>
194 argument. For example,
195 <varname>rd.luks.uuid=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40
196 <varname>rd.luks.options=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40=header=/luks.hdr:LABEL=hdrdev
197 <varname>rd.luks.data=
</varname>b40f1abf-
2a53-
400a-
889a-
2eccc27eaa40=/dev/sdx.
198 Hence, in this case, we will attempt to mount file system
199 residing on the block device with label
<literal>hdrdev
</literal>, and look
200 for
<literal>luks.hdr
</literal> on that file system. Said header will be used
201 to unlock (decrypt) encrypted data stored on /dev/sdx.
202 This syntax is for now only supported on a per-device basis,
203 i.e. you have to specify LUKS device UUID.
</para>
205 <para><varname>rd.luks.options=
</varname> is honored only by initial
206 RAM disk (initrd) while
<varname>luks.options=
</varname> is
207 honored by both the main system and in the initrd.
</para>
214 <title>See Also
</title>
216 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
217 <citerefentry><refentrytitle>crypttab
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
218 <citerefentry><refentrytitle>systemd-cryptsetup@.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
219 <citerefentry><refentrytitle>systemd-cryptenroll
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
220 <citerefentry project='die-net'
><refentrytitle>cryptsetup
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
221 <citerefentry><refentrytitle>systemd-fstab-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>