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" conditional='HAVE_LIBCRYPTSETUP'>
  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 class='crypttab-options'>
 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>keyfile-size=</varname></term>
 135
 136                                 <listitem><para>Specifies the maximum number
 137                                 of bytes to read from the keyfile; see
 138                                 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 139                                 for possible values and the default
 140                                 value of this option. This option is ignored
 141                                 in plain encryption mode, as the keyfile-size is then given by the key size.</para></listitem>
 142                         </varlistentry>
 143
 144
 145                         <varlistentry>
 146                                 <term><varname>keyfile-offset=</varname></term>
 147
 148                                 <listitem><para>Specifies the number
 149                                 of bytes to skip at the start of
 150                                 the keyfile; see
 151                                 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 152                                 for possible values and the default
 153                                 value of this option.</para></listitem>
 154                         </varlistentry>
 155
 156
 157                         <varlistentry>
 158                                 <term><varname>hash=</varname></term>
 159
 160                                 <listitem><para>Specifies the hash to
 161                                 use for password hashing; see
 162                                 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for possible values and
 163                                 the default value of this
 164                                 option. </para></listitem>
 165                         </varlistentry>
 166
 167                         <varlistentry>
 168                                 <term><varname>tries=</varname></term>
 169
 170                                 <listitem><para>Specifies the maximum
 171                                 number of times the user is queried
 172                                 for a password.</para></listitem>
 173                         </varlistentry>
 174
 175                         <varlistentry>
 176                                 <term><varname>verify</varname></term>
 177
 178                                 <listitem><para> If the encryption
 179                                 password is read from console, it has
 180                                 to be entered twice (to prevent
 181                                 typos). </para></listitem>
 182                         </varlistentry>
 183
 184                         <varlistentry>
 185                                 <term><varname>read-only</varname></term><term><varname>readonly</varname></term>
 186
 187                                 <listitem><para>Set up the encrypted
 188                                 block device in read-only
 189                                 mode.</para></listitem>
 190                         </varlistentry>
 191
 192                         <varlistentry>
 193                                 <term><varname>allow-discards</varname></term>
 194
 195                                 <listitem><para>Allow discard requests
 196                                 to be passed through the encrypted
 197                                 block device. This improves
 198                                 performance on SSD storage but has
 199                                 security
 200                                 implications.</para></listitem>
 201                         </varlistentry>
 202
 203                         <varlistentry>
 204                                 <term><varname>luks</varname></term>
 205
 206                                 <listitem><para>Force LUKS mode.</para></listitem>
 207                         </varlistentry>
 208
 209                         <varlistentry>
 210                                 <term><varname>plain</varname></term>
 211
 212                                 <listitem><para>Force plain encryption
 213                                 mode.</para></listitem>
 214                         </varlistentry>
 215
 216                         <varlistentry>
 217                                 <term><varname>timeout=</varname></term>
 218
 219                                 <listitem><para>Specify the timeout
 220                                 for querying for a password. If no
 221                                 unit is specified seconds is used.
 222                                 Supported units are s, ms,
 223                                 us, min, h, d. A timeout of 0 waits
 224                                 indefinitely.</para></listitem>
 225                         </varlistentry>
 226
 227                         <varlistentry>
 228                                 <term><varname>noauto</varname></term>
 229
 230                                 <listitem><para> This device will not
 231                                 be automatically unlocked on
 232                                 boot. </para></listitem>
 233                         </varlistentry>
 234
 235                         <varlistentry>
 236                                 <term><varname>nofail</varname></term>
 237
 238                                 <listitem><para>The system will not
 239                                 wait for the device to show up and be
 240                                 unlocked at boot, and not fail the
 241                                 boot if it doesn't show
 242                                 up.</para></listitem>
 243                         </varlistentry>
 244
 245                         <varlistentry>
 246                                 <term><varname>swap</varname></term>
 247
 248                                 <listitem><para> The encrypted block
 249                                 device will be used as a swap
 250                                 partition, and will be formatted as a
 251                                 swap partition after setting up the
 252                                 encrypted block device, with
 253                                 <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 254
 255                                 <para>WARNING: Using the
 256                                 <varname>swap</varname> option will
 257                                 destroy the contents of the named
 258                                 partition during every boot, so make
 259                                 sure the underlying block device is
 260                                 specified
 261                                 correctly. </para></listitem>
 262                         </varlistentry>
 263
 264                         <varlistentry>
 265                                 <term><varname>tmp</varname></term>
 266
 267                                 <listitem><para>The encrypted block
 268                                 device will be prepared for using it
 269                                 as <filename>/tmp</filename>
 270                                 partition: it will be formatted using
 271                                 <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 272
 273                                 <para>WARNING: Using the
 274                                 <varname>tmp</varname> option will
 275                                 destroy the contents of the named
 276                                 partition during every boot, so make
 277                                 sure the underlying block device is
 278                                 specified
 279                                 correctly. </para></listitem>
 280                         </varlistentry>
 281                 </variablelist>
 282
 283                 <para>At early boot and when the system manager
 284                 configuration is reloaded this file is translated into
 285                 native systemd units
 286                 by <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 287         </refsect1>
 288
 289         <refsect1>
 290                 <title>Example</title>
 291                 <example>
 292                         <title>/etc/crypttab example</title>
 293                         <para>Set up two encrypted block devices with
 294                         LUKS: one normal one for storage, and another
 295                         one for usage as swap device.</para>
 296
 297                         <programlisting>luks-2505567a-9e27-4efe-a4d5-15ad146c258b UUID=2505567a-9e27-4efe-a4d5-15ad146c258b - timeout=0
 298 swap /dev/sda7 /dev/urandom swap</programlisting>
 299                 </example>
 300         </refsect1>
 301
 302         <refsect1>
 303                 <title>See Also</title>
 304                 <para>
 305                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 306                         <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 307                         <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 308                         <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 309                         <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 310                         <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 311                 </para>
 312         </refsect1>
 313
 314 </refentry>