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 describes
  68     encrypted block devices that are set up during system boot.</para>
  69
  70     <para>Empty lines and lines starting with the <literal>#</literal>
  71     character are ignored. Each of the remaining lines describes one
  72     encrypted block device. Fields are delimited by white space.</para>
  73
  74     <para>Each line is in the form<programlisting><replaceable>name</replaceable> <replaceable>encrypted-device</replaceable> <replaceable>password</replaceable> <replaceable>options</replaceable></programlisting>
  75     The first two fields are mandatory, the remaining two are
  76     optional.</para>
  77
  78     <para>Setting up encrypted block devices using this file supports
  79     three encryption modes: LUKS, TrueCrypt and plain. See
  80     <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  81     for more information about each mode. When no mode is specified in
  82     the options field and the block device contains a LUKS signature,
  83     it is opened as a LUKS device; otherwise, it is assumed to be in
  84     raw dm-crypt (plain mode) format.</para>
  85
  86     <para>The first field contains the name of the resulting encrypted
  87     block device; the device is set up within
  88     <filename>/dev/mapper/</filename>.</para>
  89
  90     <para>The second field contains a path to the underlying block
  91     device or file, or a specification of a block device via
  92     <literal>UUID=</literal> followed by the UUID.</para>
  93
  94     <para>The third field specifies the encryption password. If the
  95     field is not present or the password is set to
  96     <literal>none</literal> or <literal>-</literal>, the password has
  97     to be manually entered during system boot. Otherwise, the field is
  98     interpreted as an absolute path to a file containing the encryption
  99     password. For swap encryption, <filename>/dev/urandom</filename>
 100     or the hardware device <filename>/dev/hw_random</filename> can be
 101     used as the password file; using <filename>/dev/random</filename>
 102     may prevent boot completion if the system does not have enough
 103     entropy to generate a truly random encryption key.</para>
 104
 105     <para>The fourth field, if present, is a comma-delimited list of
 106     options. The following options are recognized:</para>
 107
 108     <variablelist class='fstab-options'>
 109
 110       <varlistentry>
 111         <term><option>cipher=</option></term>
 112
 113         <listitem><para>Specifies the cipher to use. See
 114         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 115         for possible values and the default value of this option. A
 116         cipher with unpredictable IV values, such as
 117         <literal>aes-cbc-essiv:sha256</literal>, is
 118         recommended.</para></listitem>
 119       </varlistentry>
 120
 121       <varlistentry>
 122         <term><option>discard</option></term>
 123
 124         <listitem><para>Allow discard requests to be passed through the encrypted block
 125         device. This improves performance on SSD storage but has security implications.
 126         </para></listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><option>hash=</option></term>
 131
 132         <listitem><para>Specifies the hash to use for password
 133         hashing. See
 134         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 135         for possible values and the default value of this
 136         option.</para></listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term><option>header=</option></term>
 141
 142         <listitem><para>Use a detached (separated) metadata device or
 143         file where the LUKS header is stored. This option is only
 144         relevant for LUKS devices. See
 145         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 146         for possible values and the default value of this
 147         option.</para></listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term><option>keyfile-offset=</option></term>
 152
 153         <listitem><para>Specifies the number of bytes to skip at the
 154         start of the key file. See
 155         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 156         for possible values and the default value of this
 157         option.</para></listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term><option>keyfile-size=</option></term>
 162
 163         <listitem><para>Specifies the maximum number of bytes to read
 164         from the key file. See
 165         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 166         for possible values and the default value of this option. This
 167         option is ignored in plain encryption mode, as the key file
 168         size is then given by the key size.</para></listitem>
 169       </varlistentry>
 170
 171       <varlistentry>
 172         <term><option>key-slot=</option></term>
 173
 174         <listitem><para>Specifies the key slot to compare the
 175         passphrase or key against. If the key slot does not match the
 176         given passphrase or key, but another would, the setup of the
 177         device will fail regardless. This option implies
 178         <option>luks</option>. See
 179         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 180         for possible values. The default is to try all key slots in
 181         sequential order.</para></listitem>
 182       </varlistentry>
 183
 184       <varlistentry>
 185         <term><option>luks</option></term>
 186
 187         <listitem><para>Force LUKS mode. When this mode is used, the
 188         following options are ignored since they are provided by the
 189         LUKS header on the device: <option>cipher=</option>,
 190         <option>hash=</option>,
 191         <option>size=</option>.</para></listitem>
 192       </varlistentry>
 193
 194       <varlistentry>
 195         <term><option>noauto</option></term>
 196
 197         <listitem><para>This device will not be automatically unlocked
 198         on boot.</para></listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><option>nofail</option></term>
 203
 204         <listitem><para>The system will not wait for the device to
 205         show up and be unlocked at boot, and not fail the boot if it
 206         does not show up.</para></listitem>
 207       </varlistentry>
 208
 209       <varlistentry>
 210         <term><option>offset=</option></term>
 211
 212         <listitem><para>Start offset in the backend device, in 512-byte sectors. This
 213         option is only relevant for plain devices.</para></listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term><option>plain</option></term>
 218
 219         <listitem><para>Force plain encryption mode.</para></listitem>
 220       </varlistentry>
 221
 222       <varlistentry>
 223         <term><option>read-only</option></term><term><option>readonly</option></term>
 224
 225         <listitem><para>Set up the encrypted block device in read-only
 226         mode.</para></listitem>
 227       </varlistentry>
 228
 229       <varlistentry>
 230         <term><option>skip=</option></term>
 231
 232         <listitem><para>How many 512-byte sectors of the encrypted data to skip at the
 233         beginning. This is different from the <option>offset=</option> option with respect
 234         to the sector numbers used in initialization vector (IV) calculation. Using
 235         <option>offset=</option> will shift the IV calculation by the same negative
 236         amount. Hence, if <option>offset=<replaceable>n</replaceable></option> is given,
 237         sector <replaceable>n</replaceable> will get a sector number of 0 for the IV
 238         calculation. Using <option>skip=</option> causes sector
 239         <replaceable>n</replaceable> to also be the first sector of the mapped device, but
 240         with its number for IV generation being <replaceable>n</replaceable>.</para>
 241
 242         <para>This option is only relevant for plain devices.</para>
 243         </listitem>
 244       </varlistentry>
 245
 246       <varlistentry>
 247         <term><option>size=</option></term>
 248
 249         <listitem><para>Specifies the key size in bits. See
 250         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 251         for possible values and the default value of this
 252         option.</para></listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><option>swap</option></term>
 257
 258         <listitem><para>The encrypted block device will be used as a
 259         swap device, and will be formatted accordingly after setting
 260         up the encrypted block device, with
 261         <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 262         This option implies <option>plain</option>.</para>
 263
 264         <para>WARNING: Using the <option>swap</option> option will
 265         destroy the contents of the named partition during every boot,
 266         so make sure the underlying block device is specified
 267         correctly.</para></listitem>
 268       </varlistentry>
 269
 270       <varlistentry>
 271         <term><option>tcrypt</option></term>
 272
 273         <listitem><para>Use TrueCrypt encryption mode. When this mode
 274         is used, the following options are ignored since they are
 275         provided by the TrueCrypt header on the device or do not
 276         apply:
 277         <option>cipher=</option>,
 278         <option>hash=</option>,
 279         <option>keyfile-offset=</option>,
 280         <option>keyfile-size=</option>,
 281         <option>size=</option>.</para>
 282
 283         <para>When this mode is used, the passphrase is read from the
 284         key file given in the third field. Only the first line of this
 285         file is read, excluding the new line character.</para>
 286
 287         <para>Note that the TrueCrypt format uses both passphrase and
 288         key files to derive a password for the volume. Therefore, the
 289         passphrase and all key files need to be provided. Use
 290         <option>tcrypt-keyfile=</option> to provide the absolute path
 291         to all key files. When using an empty passphrase in
 292         combination with one or more key files, use
 293         <literal>/dev/null</literal> as the password file in the third
 294         field.</para></listitem>
 295       </varlistentry>
 296
 297       <varlistentry>
 298         <term><option>tcrypt-hidden</option></term>
 299
 300         <listitem><para>Use the hidden TrueCrypt volume. This option
 301         implies <option>tcrypt</option>.</para>
 302
 303         <para>This will map the hidden volume that is inside of the
 304         volume provided in the second field. Please note that there is
 305         no protection for the hidden volume if the outer volume is
 306         mounted instead. See
 307         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 308         for more information on this limitation.</para></listitem>
 309       </varlistentry>
 310
 311       <varlistentry>
 312         <term><option>tcrypt-keyfile=</option></term>
 313
 314         <listitem><para>Specifies the absolute path to a key file to
 315         use for a TrueCrypt volume. This implies
 316         <option>tcrypt</option> and can be used more than once to
 317         provide several key files.</para>
 318
 319         <para>See the entry for <option>tcrypt</option> on the
 320         behavior of the passphrase and key files when using TrueCrypt
 321         encryption mode.</para></listitem>
 322       </varlistentry>
 323
 324       <varlistentry>
 325         <term><option>tcrypt-system</option></term>
 326
 327         <listitem><para>Use TrueCrypt in system encryption mode. This
 328         option implies <option>tcrypt</option>.</para></listitem>
 329       </varlistentry>
 330
 331       <varlistentry>
 332         <term><option>tcrypt-veracrypt</option></term>
 333
 334         <listitem><para>Check for a VeraCrypt volume.  VeraCrypt is a fork of
 335         TrueCrypt that is mostly compatible, but uses different, stronger key
 336         derivation algorithms that cannot be detected without this flag.
 337         Enabling this option could substantially slow down unlocking, because
 338         VeraCrypt's key derivation takes much longer than TrueCrypt's.  This
 339         option implies <option>tcrypt</option>.</para></listitem>
 340       </varlistentry>
 341
 342       <varlistentry>
 343         <term><option>timeout=</option></term>
 344
 345         <listitem><para>Specifies the timeout for querying for a
 346         password. If no unit is specified, seconds is used. Supported
 347         units are s, ms, us, min, h, d. A timeout of 0 waits
 348         indefinitely (which is the default).</para></listitem>
 349       </varlistentry>
 350
 351       <varlistentry>
 352         <term><option>tmp</option></term>
 353
 354         <listitem><para>The encrypted block device will be prepared
 355         for using it as <filename>/tmp</filename>; it will be
 356         formatted using
 357         <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 358         This option implies <option>plain</option>.</para>
 359
 360         <para>WARNING: Using the <option>tmp</option> option will
 361         destroy the contents of the named partition during every boot,
 362         so make sure the underlying block device is specified
 363         correctly.</para></listitem>
 364       </varlistentry>
 365
 366       <varlistentry>
 367         <term><option>tries=</option></term>
 368
 369         <listitem><para>Specifies the maximum number of times the user
 370         is queried for a password. The default is 3. If set to 0, the
 371         user is queried for a password indefinitely.</para></listitem>
 372       </varlistentry>
 373
 374       <varlistentry>
 375         <term><option>verify</option></term>
 376
 377         <listitem><para> If the encryption password is read from
 378         console, it has to be entered twice to prevent
 379         typos.</para></listitem>
 380       </varlistentry>
 381
 382       <varlistentry>
 383         <term><option>x-systemd.device-timeout=</option></term>
 384
 385         <listitem><para>Specifies how long systemd should wait for a device to show up
 386         before giving up on the entry. The argument is a time in seconds or explicitly
 387         specified units of
 388         <literal>s</literal>,
 389         <literal>min</literal>,
 390         <literal>h</literal>,
 391         <literal>ms</literal>.
 392         </para></listitem>
 393       </varlistentry>
 394
 395     </variablelist>
 396
 397     <para>At early boot and when the system manager configuration is
 398     reloaded, this file is translated into native systemd units by
 399     <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 400   </refsect1>
 401
 402   <refsect1>
 403     <title>Example</title>
 404     <example>
 405       <title>/etc/crypttab example</title>
 406       <para>Set up four encrypted block devices. One using LUKS for
 407       normal storage, another one for usage as a swap device and two
 408       TrueCrypt volumes.</para>
 409
 410       <programlisting>luks       UUID=2505567a-9e27-4efe-a4d5-15ad146c258b
 411 swap       /dev/sda7       /dev/urandom       swap
 412 truecrypt  /dev/sda2       /etc/container_password  tcrypt
 413 hidden     /mnt/tc_hidden  /dev/null    tcrypt-hidden,tcrypt-keyfile=/etc/keyfile</programlisting>
 414     </example>
 415   </refsect1>
 416
 417   <refsect1>
 418     <title>See Also</title>
 419     <para>
 420       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 421       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 422       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 423       <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 424       <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 425       <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 426     </para>
 427   </refsect1>
 428
 429 </refentry>