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-or-later -->
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>This parameter is the analogue of the first <citerefentry><refentrytitle>crypttab</refentrytitle>
109        <manvolnum>5</manvolnum></citerefentry> field <replaceable>volume-name</replaceable>.</para>
110
111        <para><varname>rd.luks.name=</varname> is honored only by
112        initial RAM disk (initrd) while <varname>luks.name=</varname>
113        is honored by both the main system and the initrd.</para>
114        </listitem>
115      </varlistentry>
116
117      <varlistentry>
118        <term><varname>luks.data=</varname></term>
119        <term><varname>rd.luks.data=</varname></term>
120
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>
123
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>
127
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>
136
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>
139
140        <para><varname>rd.luks.data=</varname> is honored only by initial RAM disk (initrd) while
141        <varname>luks.data=</varname> is honored by both the main system and the initrd.</para>
142        </listitem>
143      </varlistentry>
144
145      <varlistentry>
146        <term><varname>luks.key=</varname></term>
147        <term><varname>rd.luks.key=</varname></term>
148
149        <listitem><para>Takes a password file name as argument or a
150        LUKS super block UUID followed by a <literal>=</literal> and a
151        password file name.</para>
152
153        <para>For those entries specified with
154        <varname>rd.luks.uuid=</varname> or
155        <varname>luks.uuid=</varname>, the password file will be set
156        to the one specified by <varname>rd.luks.key=</varname> or
157        <varname>luks.key=</varname> of the corresponding UUID, or the
158        password file that was specified without a UUID.</para>
159
160        <para>It is also possible to specify an external device which
161        should be mounted before we attempt to unlock the LUKS device.
162        systemd-cryptsetup will use password file stored on that
163        device. Device containing password file is specified by
164        appending colon and a device identifier to the password file
165        path. For example,
166        <varname>rd.luks.uuid=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40
167        <varname>rd.luks.key=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40=/keyfile:LABEL=keydev.
168        Hence, in this case, we will attempt to mount file system
169        residing on the block device with label <literal>keydev</literal>.
170        This syntax is for now only supported on a per-device basis,
171        i.e. you have to specify LUKS device UUID.</para>
172
173        <para>This parameter is the analogue of the third <citerefentry><refentrytitle>crypttab</refentrytitle>
174        <manvolnum>5</manvolnum></citerefentry> field <replaceable>key-file</replaceable>.</para>
175
176        <para><varname>rd.luks.key=</varname>
177        is honored only by initial RAM disk
178        (initrd) while
179        <varname>luks.key=</varname> is
180        honored by both the main system and
181        the initrd.</para>
182        </listitem>
183      </varlistentry>
184
185      <varlistentry>
186        <term><varname>luks.options=</varname></term>
187        <term><varname>rd.luks.options=</varname></term>
188
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
192        given UUID.</para>
193        <para>If only a list of options, without an UUID, is
194        specified, they apply to any UUIDs not specified elsewhere,
195        and without an entry in
196        <filename>/etc/crypttab</filename>.</para>
197
198        <para>This parameter is the analogue of the fourth <citerefentry><refentrytitle>crypttab</refentrytitle>
199        <manvolnum>5</manvolnum></citerefentry> field <replaceable>options</replaceable>.</para>
200
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>
216
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 the initrd.</para>
220        </listitem>
221      </varlistentry>
222    </variablelist>
223  </refsect1>
224
225  <refsect1>
226    <title>See Also</title>
227    <para>
228      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
229      <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
230      <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
231      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
232      <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
233      <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
234    </para>
235  </refsect1>
236
237</refentry>
238