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'
>
9 <title>systemd-cryptsetup-generator
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>systemd-cryptsetup-generator
</refentrytitle>
15 <manvolnum>8</manvolnum>
19 <refname>systemd-cryptsetup-generator
</refname>
20 <refpurpose>Unit generator for
<filename>/etc/crypttab
</filename></refpurpose>
24 <para><filename>/usr/lib/systemd/system-generators/systemd-cryptsetup-generator
</filename></para>
28 <title>Description
</title>
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>
37 <para><filename>systemd-cryptsetup-generator
</filename> implements
38 <citerefentry><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
42 <title>Kernel Command Line
</title>
44 <para><filename>systemd-cryptsetup-generator
</filename>
45 understands the following kernel command line parameters:
</para>
47 <variablelist class='kernel-commandline-options'
>
49 <term><varname>luks=
</varname></term>
50 <term><varname>rd.luks=
</varname></term>
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>
61 <term><varname>luks.crypttab=
</varname></term>
62 <term><varname>rd.luks.crypttab=
</varname></term>
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>
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
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>
98 <term><varname>luks.name=
</varname></term>
99 <term><varname>rd.luks.name=
</varname></term>
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
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>
115 <term><varname>luks.options=
</varname></term>
116 <term><varname>rd.luks.options=
</varname></term>
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
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>
133 <term><varname>luks.key=
</varname></term>
134 <term><varname>rd.luks.key=
</varname></term>
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>
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>
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
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>
160 <para><varname>rd.luks.key=
</varname>
161 is honored only by initial RAM disk
163 <varname>luks.key=
</varname> is
164 honored by both the main system and
172 <title>See Also
</title>
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>