man/crypttab.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   This is based on crypttab(5) from Fedora's initscripts package, which in
  23   turn is based on Debian's version.
  24
  25   The Red Hat version has been written by Miloslav Trmac <mitr@redhat.com>.
  26
  27 -->
  28 <refentry id="crypttab">
  29
  30         <refentryinfo>
  31                 <title>crypttab</title>
  32                 <productname>systemd</productname>
  33
  34                 <authorgroup>
  35                         <author>
  36                                 <contrib>Documentation</contrib>
  37                                 <firstname>Miloslav</firstname>
  38                                 <surname>Trmac</surname>
  39                                 <email>mitr@redhat.com</email>
  40                         </author>
  41                         <author>
  42                                 <contrib>Documentation</contrib>
  43                                 <firstname>Lennart</firstname>
  44                                 <surname>Poettering</surname>
  45                                 <email>lennart@poettering.net</email>
  46                         </author>
  47                 </authorgroup>
  48         </refentryinfo>
  49
  50         <refmeta>
  51                 <refentrytitle>crypttab</refentrytitle>
  52                 <manvolnum>5</manvolnum>
  53         </refmeta>
  54
  55         <refnamediv>
  56                 <refname>crypttab</refname>
  57                 <refpurpose>Configuration for encrypted block devices</refpurpose>
  58         </refnamediv>
  59
  60         <refsynopsisdiv>
  61                 <para><filename>/etc/crypttab</filename></para>
  62         </refsynopsisdiv>
  63
  64         <refsect1>
  65                 <title>Description</title>
  66
  67                 <para>The <filename>/etc/crypttab</filename> file
  68                 describes encrypted block devices that are set up
  69                 during system boot.</para>
  70
  71                 <para>Empty lines and lines starting with the #
  72                 character are ignored.  Each of the remaining lines
  73                 describes one encrypted block device, fields on the
  74                 line are delimited by white space.  The first two
  75                 fields are mandatory, the remaining two are
  76                 optional.</para>
  77
  78                 <para>The first field contains the name of the
  79                 resulting encrypted block device; the device is set up
  80                 within <filename>/dev/mapper/</filename>.</para>
  81
  82                 <para>The second field contains a path to the
  83                 underlying block device, or a specification of a block
  84                 device via <literal>UUID=</literal> followed by the
  85                 UUID.  If the block device contains a LUKS signature,
  86                 it is opened as a LUKS encrypted partition; otherwise
  87                 it is assumed to be a raw dm-crypt partition.</para>
  88
  89                 <para>The third field specifies the encryption
  90                 password.  If the field is not present or the password
  91                 is set to none, the password has to be manually
  92                 entered during system boot.  Otherwise the field is
  93                 interpreted as a path to a file containing the
  94                 encryption password.  For swap encryption
  95                 <filename>/dev/urandom</filename> or the hardware
  96                 device <filename>/dev/hw_random</filename> can be used
  97                 as the password file; using
  98                 <filename>/dev/random</filename> may prevent boot
  99                 completion if the system does not have enough entropy
 100                 to generate a truly random encryption key.</para>
 101
 102                 <para>The fourth field, if present, is a
 103                 comma-delimited list of options.  The following
 104                 options are recognized:</para>
 105
 106                 <variablelist>
 107                         <varlistentry>
 108                                 <term><varname>cipher=</varname></term>
 109
 110                                 <listitem><para>Specifies the cipher
 111                                 to use; see
 112                                 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 113                                 for possible values and the default
 114                                 value of this option.  A cipher with
 115                                 unpredictable IV values, such as
 116                                 <literal>aes-cbc-essiv:sha256</literal>,
 117                                 is recommended. </para></listitem>
 118                         </varlistentry>
 119
 120
 121                         <varlistentry>
 122                                 <term><varname>size=</varname></term>
 123
 124                                 <listitem><para>Specifies the key size
 125                                 in bits; see
 126                                 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 127                                 for possible values and the default
 128                                 value of this
 129                                 option. </para></listitem>
 130                         </varlistentry>
 131
 132
 133                         <varlistentry>
 134                                 <term><varname>hash=</varname></term>
 135
 136                                 <listitem><para>Specifies the hash to
 137                                 use for password hashing; see
 138                                 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for possible values and
 139                                 the default value of this
 140                                 option. </para></listitem>
 141                         </varlistentry>
 142
 143                         <varlistentry>
 144                                 <term><varname>tries=</varname></term>
 145
 146                                 <listitem><para>Specifies the maximum
 147                                 number of times the user is queried
 148                                 for a password.</para></listitem>
 149                         </varlistentry>
 150
 151                         <varlistentry>
 152                                 <term><varname>verify</varname></term>
 153
 154                                 <listitem><para> If the the encryption
 155                                 password is read from console, it has
 156                                 to be entered twice (to prevent
 157                                 typos). </para></listitem>
 158                         </varlistentry>
 159
 160                         <varlistentry>
 161                                 <term><varname>read-only</varname></term>
 162
 163                                 <listitem><para>Set up the encrypted
 164                                 block device in read-only
 165                                 mode.</para></listitem>
 166                         </varlistentry>
 167
 168                         <varlistentry>
 169                                 <term><varname>allow-discards</varname></term>
 170
 171                                 <listitem><para>Allow discard requests
 172                                 to be passed through the encrypted
 173                                 block device. This improves
 174                                 performance on SSD storage but has
 175                                 security
 176                                 implications.</para></listitem>
 177                         </varlistentry>
 178
 179                         <varlistentry>
 180                                 <term><varname>luks</varname></term>
 181
 182                                 <listitem><para>Force LUKS mode.</para></listitem>
 183                         </varlistentry>
 184
 185                         <varlistentry>
 186                                 <term><varname>plain</varname></term>
 187
 188                                 <listitem><para>Force plain encryption
 189                                 mode.</para></listitem>
 190                         </varlistentry>
 191
 192                         <varlistentry>
 193                                 <term><varname>timeout=</varname></term>
 194
 195                                 <listitem><para>Specify the timeout
 196                                 for querying for a password. If not
 197                                 unit is specified in
 198                                 seconds. Supported units are s, ms,
 199                                 us, min, h, d.</para></listitem>
 200                         </varlistentry>
 201
 202                         <varlistentry>
 203                                 <term><varname>noauto</varname></term>
 204
 205                                 <listitem><para> This device will not
 206                                 be automatically unlocked on
 207                                 boot. </para></listitem>
 208                         </varlistentry>
 209
 210                         <varlistentry>
 211                                 <term><varname>nofail</varname></term>
 212
 213                                 <listitem><para>The system will not
 214                                 wait for the device to show up and be
 215                                 unlocked at boot, and not fail the
 216                                 boot if it doesn't show
 217                                 up.</para></listitem>
 218                         </varlistentry>
 219
 220                         <varlistentry>
 221                                 <term><varname>swap</varname></term>
 222
 223                                 <listitem><para> The encrypted block
 224                                 device will be used as a swap
 225                                 partition, and will be formatted as a
 226                                 swap partition after setting up the
 227                                 encrypted block device, with
 228                                 <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 229
 230                                 <para>WARNING: Using the
 231                                 <varname>swap</varname> option will
 232                                 destroy the contents of the named
 233                                 partition during every boot, so make
 234                                 sure the underlying block device is
 235                                 specified
 236                                 correctly. </para></listitem>
 237                         </varlistentry>
 238
 239                         <varlistentry>
 240                                 <term><varname>tmp</varname></term>
 241
 242                                 <listitem><para>The encrypted block
 243                                 device will be prepared for using it
 244                                 as <filename>/tmp</filename>
 245                                 partition: it will be formatted using
 246                                 <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 247
 248                                 <para>WARNING: Using the
 249                                 <varname>tmp</varname> option will
 250                                 destroy the contents of the named
 251                                 partition during every boot, so make
 252                                 sure the underlying block device is
 253                                 specified
 254                                 correctly. </para></listitem>
 255                         </varlistentry>
 256                 </variablelist>
 257
 258                 <para>At early boot and when the system manager
 259                 configuration is reloaded this file is translated into
 260                 native systemd units
 261                 by <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 262         </refsect1>
 263
 264         <refsect1>
 265                 <title>Example</title>
 266                 <example>
 267                         <title>/etc/crypttab example</title>
 268                         <para>Set up two encrypted block devices with
 269                         LUKS: one normal one for storage, and another
 270                         one for usage as swap device.</para>
 271
 272                         <programlisting>luks-2505567a-9e27-4efe-a4d5-15ad146c258b UUID=2505567a-9e27-4efe-a4d5-15ad146c258b - timeout=0
 273 swap /dev/sda7 /dev/urandom swap</programlisting>
 274                 </example>
 275         </refsect1>
 276
 277         <refsect1>
 278                 <title>See Also</title>
 279                 <para>
 280                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 281                         <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 282                         <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 283                         <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 284                         <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 285                         <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 286                 </para>
 287         </refsect1>
 288
 289 </refentry>