man/systemd-cryptsetup-generator.xml - systemd-stable - Rivoreo Source Code Repositories

 <?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-or-later -->
 <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>
	<?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-or-later -->
	<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>