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>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 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>
 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 not
 221                                 unit is specified in
 222                                 seconds. Supported units are s, ms,
 223                                 us, min, h, d.</para></listitem>
 224                         </varlistentry>
 225
 226                         <varlistentry>
 227                                 <term><varname>noauto</varname></term>
 228
 229                                 <listitem><para> This device will not
 230                                 be automatically unlocked on
 231                                 boot. </para></listitem>
 232                         </varlistentry>
 233
 234                         <varlistentry>
 235                                 <term><varname>nofail</varname></term>
 236
 237                                 <listitem><para>The system will not
 238                                 wait for the device to show up and be
 239                                 unlocked at boot, and not fail the
 240                                 boot if it doesn't show
 241                                 up.</para></listitem>
 242                         </varlistentry>
 243
 244                         <varlistentry>
 245                                 <term><varname>swap</varname></term>
 246
 247                                 <listitem><para> The encrypted block
 248                                 device will be used as a swap
 249                                 partition, and will be formatted as a
 250                                 swap partition after setting up the
 251                                 encrypted block device, with
 252                                 <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 253
 254                                 <para>WARNING: Using the
 255                                 <varname>swap</varname> option will
 256                                 destroy the contents of the named
 257                                 partition during every boot, so make
 258                                 sure the underlying block device is
 259                                 specified
 260                                 correctly. </para></listitem>
 261                         </varlistentry>
 262
 263                         <varlistentry>
 264                                 <term><varname>tmp</varname></term>
 265
 266                                 <listitem><para>The encrypted block
 267                                 device will be prepared for using it
 268                                 as <filename>/tmp</filename>
 269                                 partition: it will be formatted using
 270                                 <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 271
 272                                 <para>WARNING: Using the
 273                                 <varname>tmp</varname> option will
 274                                 destroy the contents of the named
 275                                 partition during every boot, so make
 276                                 sure the underlying block device is
 277                                 specified
 278                                 correctly. </para></listitem>
 279                         </varlistentry>
 280                 </variablelist>
 281
 282                 <para>At early boot and when the system manager
 283                 configuration is reloaded this file is translated into
 284                 native systemd units
 285                 by <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 286         </refsect1>
 287
 288         <refsect1>
 289                 <title>Example</title>
 290                 <example>
 291                         <title>/etc/crypttab example</title>
 292                         <para>Set up two encrypted block devices with
 293                         LUKS: one normal one for storage, and another
 294                         one for usage as swap device.</para>
 295
 296                         <programlisting>luks-2505567a-9e27-4efe-a4d5-15ad146c258b UUID=2505567a-9e27-4efe-a4d5-15ad146c258b - timeout=0
 297 swap /dev/sda7 /dev/urandom swap</programlisting>
 298                 </example>
 299         </refsect1>
 300
 301         <refsect1>
 302                 <title>See Also</title>
 303                 <para>
 304                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 305                         <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 306                         <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 307                         <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 308                         <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 309                         <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 310                 </para>
 311         </refsect1>
 312
 313 </refentry>