| <?xml version="1.0"?> |
| <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| <!-- SPDX-License-Identifier: LGPL-2.1+ --> |
| <refentry id="systemd-cryptsetup-generator" conditional='HAVE_LIBCRYPTSETUP'> |
| |
| <refentryinfo> |
| <title>systemd-cryptsetup-generator</title> |
| <productname>systemd</productname> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>systemd-cryptsetup-generator</refentrytitle> |
| <manvolnum>8</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>systemd-cryptsetup-generator</refname> |
| <refpurpose>Unit generator for <filename>/etc/crypttab</filename></refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <para><filename>/usr/lib/systemd/system-generators/systemd-cryptsetup-generator</filename></para> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para><filename>systemd-cryptsetup-generator</filename> is a |
| generator that translates <filename>/etc/crypttab</filename> into |
| native systemd units early at boot and when configuration of the |
| system manager is reloaded. This will create |
| <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| units as necessary.</para> |
| |
| <para><filename>systemd-cryptsetup-generator</filename> implements |
| <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Kernel Command Line</title> |
| |
| <para><filename>systemd-cryptsetup-generator</filename> |
| understands the following kernel command line parameters:</para> |
| |
| <variablelist class='kernel-commandline-options'> |
| <varlistentry> |
| <term><varname>luks=</varname></term> |
| <term><varname>rd.luks=</varname></term> |
| |
| <listitem><para>Takes a boolean argument. Defaults to |
| <literal>yes</literal>. If <literal>no</literal>, disables the |
| generator entirely. <varname>rd.luks=</varname> is honored |
| only by initial RAM disk (initrd) while |
| <varname>luks=</varname> is honored by both the main system |
| and the initrd. </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>luks.crypttab=</varname></term> |
| <term><varname>rd.luks.crypttab=</varname></term> |
| |
| <listitem><para>Takes a boolean argument. Defaults to |
| <literal>yes</literal>. If <literal>no</literal>, causes the |
| generator to ignore any devices configured in |
| <filename>/etc/crypttab</filename> |
| (<varname>luks.uuid=</varname> will still work however). |
| <varname>rd.luks.crypttab=</varname> is honored only by |
| initial RAM disk (initrd) while |
| <varname>luks.crypttab=</varname> is honored by both the main |
| system and the initrd. </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>luks.uuid=</varname></term> |
| <term><varname>rd.luks.uuid=</varname></term> |
| |
| <listitem><para>Takes a LUKS superblock UUID as argument. This |
| will activate the specified device as part of the boot process |
| as if it was listed in <filename>/etc/crypttab</filename>. |
| This option may be specified more than once in order to set up |
| multiple devices. <varname>rd.luks.uuid=</varname> is honored |
| only by initial RAM disk (initrd) while |
| <varname>luks.uuid=</varname> is honored by both the main |
| system and the initrd.</para> |
| <para>If /etc/crypttab contains entries with the same UUID, |
| then the name, keyfile and options specified there will be |
| used. Otherwise, the device will have the name |
| <literal>luks-UUID</literal>.</para> |
| <para>If /etc/crypttab exists, only those UUIDs |
| specified on the kernel command line |
| will be activated in the initrd or the real root.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>luks.name=</varname></term> |
| <term><varname>rd.luks.name=</varname></term> |
| |
| <listitem><para>Takes a LUKS super block UUID followed by an |
| <literal>=</literal> and a name. This implies |
| <varname>rd.luks.uuid=</varname> or |
| <varname>luks.uuid=</varname> and will additionally make the |
| LUKS device given by the UUID appear under the provided |
| name.</para> |
| |
| <para>This parameter is the analogue of the first <citerefentry><refentrytitle>crypttab</refentrytitle> |
| <manvolnum>5</manvolnum></citerefentry> field <replaceable>volume-name</replaceable>.</para> |
| |
| <para><varname>rd.luks.name=</varname> is honored only by |
| initial RAM disk (initrd) while <varname>luks.name=</varname> |
| is honored by both the main system and the initrd.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>luks.data=</varname></term> |
| <term><varname>rd.luks.data=</varname></term> |
| |
| <listitem><para>Takes a LUKS super block UUID followed by a <literal>=</literal> and a block device |
| specification for device hosting encrypted data.</para> |
| |
| <para>For those entries specified with <varname>rd.luks.uuid=</varname> or |
| <varname>luks.uuid=</varname>, the data device will be set to the one specified by |
| <varname>rd.luks.data=</varname> or <varname>luks.data=</varname> of the corresponding UUID.</para> |
| |
| <para>LUKS data device parameter is useful for specifying encrypted data devices with detached headers specified in |
| <varname>luks.options</varname> entry containing <literal>header=</literal> argument. For example, |
| <varname>rd.luks.uuid=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40 |
| <varname>rd.luks.options=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40=header=/path/to/luks.hdr |
| <varname>rd.luks.data=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40=/dev/sdx. |
| Hence, in this case, we will attempt to unlock LUKS device assembled from data device <literal>/dev/sdx</literal> |
| and LUKS header (metadata) put in <literal>/path/to/luks.hdr</literal> file. This syntax is for now |
| only supported on a per-device basis, i.e. you have to specify LUKS device UUID.</para> |
| |
| <para>This parameter is the analogue of the second <citerefentry><refentrytitle>crypttab</refentrytitle> |
| <manvolnum>5</manvolnum></citerefentry> field <replaceable>encrypted-device</replaceable>.</para> |
| |
| <para><varname>rd.luks.data=</varname> is honored only by initial RAM disk (initrd) while |
| <varname>luks.data=</varname> is honored by both the main system and the initrd.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>luks.key=</varname></term> |
| <term><varname>rd.luks.key=</varname></term> |
| |
| <listitem><para>Takes a password file name as argument or a |
| LUKS super block UUID followed by a <literal>=</literal> and a |
| password file name.</para> |
| |
| <para>For those entries specified with |
| <varname>rd.luks.uuid=</varname> or |
| <varname>luks.uuid=</varname>, the password file will be set |
| to the one specified by <varname>rd.luks.key=</varname> or |
| <varname>luks.key=</varname> of the corresponding UUID, or the |
| password file that was specified without a UUID.</para> |
| |
| <para>It is also possible to specify an external device which |
| should be mounted before we attempt to unlock the LUKS device. |
| systemd-cryptsetup will use password file stored on that |
| device. Device containing password file is specified by |
| appending colon and a device identifier to the password file |
| path. For example, |
| <varname>rd.luks.uuid=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40 |
| <varname>rd.luks.key=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40=/keyfile:LABEL=keydev. |
| Hence, in this case, we will attempt to mount file system |
| residing on the block device with label <literal>keydev</literal>. |
| This syntax is for now only supported on a per-device basis, |
| i.e. you have to specify LUKS device UUID.</para> |
| |
| <para>This parameter is the analogue of the third <citerefentry><refentrytitle>crypttab</refentrytitle> |
| <manvolnum>5</manvolnum></citerefentry> field <replaceable>key-file</replaceable>.</para> |
| |
| <para><varname>rd.luks.key=</varname> |
| is honored only by initial RAM disk |
| (initrd) while |
| <varname>luks.key=</varname> is |
| honored by both the main system and |
| the initrd.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>luks.options=</varname></term> |
| <term><varname>rd.luks.options=</varname></term> |
| |
| <listitem><para>Takes a LUKS super block UUID followed by an |
| <literal>=</literal> and a string of options separated by |
| commas as argument. This will override the options for the |
| given UUID.</para> |
| <para>If only a list of options, without an UUID, is |
| specified, they apply to any UUIDs not specified elsewhere, |
| and without an entry in |
| <filename>/etc/crypttab</filename>.</para> |
| |
| <para>This parameter is the analogue of the fourth <citerefentry><refentrytitle>crypttab</refentrytitle> |
| <manvolnum>5</manvolnum></citerefentry> field <replaceable>options</replaceable>.</para> |
| |
| <para>It is possible to specify an external device which |
| should be mounted before we attempt to unlock the LUKS device. |
| systemd-cryptsetup will assemble LUKS device by combining |
| data device specified in <varname>luks.data</varname> with |
| detached LUKS header found in <literal>header=</literal> |
| argument. For example, |
| <varname>rd.luks.uuid=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40 |
| <varname>rd.luks.options=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40=header=/luks.hdr:LABEL=hdrdev |
| <varname>rd.luks.data=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40=/dev/sdx. |
| Hence, in this case, we will attempt to mount file system |
| residing on the block device with label <literal>hdrdev</literal>, and look |
| for <literal>luks.hdr</literal> on that file system. Said header will be used |
| to unlock (decrypt) encrypted data stored on /dev/sdx. |
| This syntax is for now only supported on a per-device basis, |
| i.e. you have to specify LUKS device UUID.</para> |
| |
| <para><varname>rd.luks.options=</varname> is honored only by initial |
| RAM disk (initrd) while <varname>luks.options=</varname> is |
| honored by both the main system and the initrd.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |