man/systemd-cryptsetup-generator.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!--
   5   This file is part of systemd.
   6
   7   Copyright 2012 Lennart Poettering
   8
   9   systemd is free software; you can redistribute it and/or modify it
  10   under the terms of the GNU Lesser General Public License as published by
  11   the Free Software Foundation; either version 2.1 of the License, or
  12   (at your option) any later version.
  13
  14   systemd is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   Lesser General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public License
  20   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  21 -->
  22 <refentry id="systemd-cryptsetup-generator" conditional='HAVE_LIBCRYPTSETUP'>
  23
  24   <refentryinfo>
  25     <title>systemd-cryptsetup-generator</title>
  26     <productname>systemd</productname>
  27
  28     <authorgroup>
  29       <author>
  30         <contrib>Developer</contrib>
  31         <firstname>Lennart</firstname>
  32         <surname>Poettering</surname>
  33         <email>lennart@poettering.net</email>
  34       </author>
  35     </authorgroup>
  36   </refentryinfo>
  37
  38   <refmeta>
  39     <refentrytitle>systemd-cryptsetup-generator</refentrytitle>
  40     <manvolnum>8</manvolnum>
  41   </refmeta>
  42
  43   <refnamediv>
  44     <refname>systemd-cryptsetup-generator</refname>
  45     <refpurpose>Unit generator for <filename>/etc/crypttab</filename></refpurpose>
  46   </refnamediv>
  47
  48   <refsynopsisdiv>
  49     <para><filename>/usr/lib/systemd/system-generators/systemd-cryptsetup-generator</filename></para>
  50   </refsynopsisdiv>
  51
  52   <refsect1>
  53     <title>Description</title>
  54
  55     <para><filename>systemd-cryptsetup-generator</filename> is a
  56     generator that translates <filename>/etc/crypttab</filename> into
  57     native systemd units early at boot and when configuration of the
  58     system manager is reloaded. This will create
  59     <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  60     units as necessary.</para>
  61
  62     <para><filename>systemd-cryptsetup-generator</filename>
  63     implements the <ulink
  64     url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator
  65     specification</ulink>.</para>
  66   </refsect1>
  67
  68   <refsect1>
  69     <title>Kernel Command Line</title>
  70
  71     <para><filename>systemd-cryptsetup-generator</filename>
  72     understands the following kernel command line parameters:</para>
  73
  74     <variablelist class='kernel-commandline-options'>
  75       <varlistentry>
  76         <term><varname>luks=</varname></term>
  77         <term><varname>rd.luks=</varname></term>
  78
  79         <listitem><para>Takes a boolean argument. Defaults to
  80         <literal>yes</literal>. If <literal>no</literal>, disables the
  81         generator entirely. <varname>rd.luks=</varname> is honored
  82         only by initial RAM disk (initrd) while
  83         <varname>luks=</varname> is honored by both the main system
  84         and the initrd. </para></listitem>
  85       </varlistentry>
  86
  87       <varlistentry>
  88         <term><varname>luks.crypttab=</varname></term>
  89         <term><varname>rd.luks.crypttab=</varname></term>
  90
  91         <listitem><para>Takes a boolean argument. Defaults to
  92         <literal>yes</literal>. If <literal>no</literal>, causes the
  93         generator to ignore any devices configured in
  94         <filename>/etc/crypttab</filename>
  95         (<varname>luks.uuid=</varname> will still work however).
  96         <varname>rd.luks.crypttab=</varname> is honored only by
  97         initial RAM disk (initrd) while
  98         <varname>luks.crypttab=</varname> is honored by both the main
  99         system and the initrd. </para></listitem>
 100       </varlistentry>
 101
 102       <varlistentry>
 103         <term><varname>luks.uuid=</varname></term>
 104         <term><varname>rd.luks.uuid=</varname></term>
 105
 106         <listitem><para>Takes a LUKS superblock UUID as argument. This
 107         will activate the specified device as part of the boot process
 108         as if it was listed in <filename>/etc/crypttab</filename>.
 109         This option may be specified more than once in order to set up
 110         multiple devices. <varname>rd.luks.uuid=</varname> is honored
 111         only by initial RAM disk (initrd) while
 112         <varname>luks.uuid=</varname> is honored by both the main
 113         system and the initrd.</para>
 114         <para>If /etc/crypttab contains entries with the same UUID,
 115         then the name, keyfile and options specified there will be
 116         used. Otherwise the device will have the name
 117         <literal>luks-UUID</literal>.</para>
 118         <para>If /etc/crypttab exists, only those UUIDs
 119         specified on the kernel command line
 120         will be activated in the initrd or the real root.</para>
 121         </listitem>
 122       </varlistentry>
 123
 124       <varlistentry>
 125         <term><varname>luks.name=</varname></term>
 126         <term><varname>rd.luks.name=</varname></term>
 127
 128         <listitem><para>Takes a LUKS super block UUID followed by an
 129         <literal>=</literal> and a name. This implies
 130         <varname>rd.luks.uuid=</varname> or
 131         <varname>luks.uuid=</varname> and will additionally make the
 132         LUKS device given by the UUID appear under the provided
 133         name.</para>
 134
 135         <para><varname>rd.luks.name=</varname> is honored only by
 136         initial RAM disk (initrd) while <varname>luks.name=</varname>
 137         is honored by both the main system and the initrd.</para>
 138         </listitem>
 139       </varlistentry>
 140
 141       <varlistentry>
 142         <term><varname>luks.options=</varname></term>
 143         <term><varname>rd.luks.options=</varname></term>
 144
 145         <listitem><para>Takes a LUKS super block UUID followed by an
 146         <literal>=</literal> and a string of options separated by
 147         commas as argument. This will override the options for the
 148         given UUID.</para>
 149         <para>If only a list of options, without an UUID, is
 150         specified, they apply to any UUIDs not specified elsewhere,
 151         and without an entry in
 152         <filename>/etc/crypttab</filename>.</para><para>
 153         <varname>rd.luks.options=</varname> is honored only by initial
 154         RAM disk (initrd) while <varname>luks.options=</varname> is
 155         honored by both the main system and the initrd.</para>
 156         </listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term><varname>luks.key=</varname></term>
 161         <term><varname>rd.luks.key=</varname></term>
 162
 163         <listitem><para>Takes a password file name as argument or a
 164         LUKS super block UUID followed by a <literal>=</literal> and a
 165         password file name.</para>
 166
 167         <para>For those entries specified with
 168         <varname>rd.luks.uuid=</varname> or
 169         <varname>luks.uuid=</varname>, the password file will be set
 170         to the one specified by <varname>rd.luks.key=</varname> or
 171         <varname>luks.key=</varname> of the corresponding UUID, or the
 172         password file that was specified without a UUID.</para>
 173         <para><varname>rd.luks.key=</varname>
 174         is honored only by initial RAM disk
 175         (initrd) while
 176         <varname>luks.key=</varname> is
 177         honored by both the main system and
 178         the initrd.</para>
 179         </listitem>
 180       </varlistentry>
 181     </variablelist>
 182   </refsect1>
 183
 184   <refsect1>
 185     <title>See Also</title>
 186     <para>
 187       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 188       <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 190       <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 191       <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 192     </para>
 193   </refsect1>
 194
 195 </refentry>