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>_netdev</option></term>
 196
 197         <listitem><para>Marks this cryptsetup device as requiring network. It will be
 198         started after the network is available, similarly to
 199         <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 200         units marked with <option>_netdev</option>. The service unit to set up this device
 201         will be ordered between <filename>remote-fs-pre.target</filename> and
 202         <filename>remote-cryptsetup.target</filename>, instead of
 203         <filename>cryptsetup-pre.target</filename> and
 204         <filename>cryptsetup.target</filename>.</para>
 205
 206         <para>Hint: if this device is used for a mount point that is specified in
 207         <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 208         the <option>_netdev</option> option should also be used for the mount
 209         point. Otherwise, a dependency loop might be created where the mount point
 210         will be pulled in by <filename>local-fs.target</filename>, while the
 211         service to configure the network is usually only started <emphasis>after</emphasis>
 212         the local file system has been mounted.</para>
 213         </listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term><option>noauto</option></term>
 218
 219         <listitem><para>This device will not be automatically unlocked
 220         on boot.</para></listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term><option>nofail</option></term>
 225
 226         <listitem><para>The system will not wait for the device to
 227         show up and be unlocked at boot, and not fail the boot if it
 228         does not show up.</para></listitem>
 229       </varlistentry>
 230
 231       <varlistentry>
 232         <term><option>offset=</option></term>
 233
 234         <listitem><para>Start offset in the backend device, in 512-byte sectors. This
 235         option is only relevant for plain devices.</para></listitem>
 236       </varlistentry>
 237
 238       <varlistentry>
 239         <term><option>plain</option></term>
 240
 241         <listitem><para>Force plain encryption mode.</para></listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term><option>read-only</option></term><term><option>readonly</option></term>
 246
 247         <listitem><para>Set up the encrypted block device in read-only
 248         mode.</para></listitem>
 249       </varlistentry>
 250
 251       <varlistentry>
 252         <term><option>skip=</option></term>
 253
 254         <listitem><para>How many 512-byte sectors of the encrypted data to skip at the
 255         beginning. This is different from the <option>offset=</option> option with respect
 256         to the sector numbers used in initialization vector (IV) calculation. Using
 257         <option>offset=</option> will shift the IV calculation by the same negative
 258         amount. Hence, if <option>offset=<replaceable>n</replaceable></option> is given,
 259         sector <replaceable>n</replaceable> will get a sector number of 0 for the IV
 260         calculation. Using <option>skip=</option> causes sector
 261         <replaceable>n</replaceable> to also be the first sector of the mapped device, but
 262         with its number for IV generation being <replaceable>n</replaceable>.</para>
 263
 264         <para>This option is only relevant for plain devices.</para>
 265         </listitem>
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term><option>size=</option></term>
 270
 271         <listitem><para>Specifies the key size in bits. See
 272         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 273         for possible values and the default value of this
 274         option.</para></listitem>
 275       </varlistentry>
 276
 277       <varlistentry>
 278         <term><option>swap</option></term>
 279
 280         <listitem><para>The encrypted block device will be used as a
 281         swap device, and will be formatted accordingly after setting
 282         up the encrypted block device, with
 283         <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 284         This option implies <option>plain</option>.</para>
 285
 286         <para>WARNING: Using the <option>swap</option> option will
 287         destroy the contents of the named partition during every boot,
 288         so make sure the underlying block device is specified
 289         correctly.</para></listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><option>tcrypt</option></term>
 294
 295         <listitem><para>Use TrueCrypt encryption mode. When this mode
 296         is used, the following options are ignored since they are
 297         provided by the TrueCrypt header on the device or do not
 298         apply:
 299         <option>cipher=</option>,
 300         <option>hash=</option>,
 301         <option>keyfile-offset=</option>,
 302         <option>keyfile-size=</option>,
 303         <option>size=</option>.</para>
 304
 305         <para>When this mode is used, the passphrase is read from the
 306         key file given in the third field. Only the first line of this
 307         file is read, excluding the new line character.</para>
 308
 309         <para>Note that the TrueCrypt format uses both passphrase and
 310         key files to derive a password for the volume. Therefore, the
 311         passphrase and all key files need to be provided. Use
 312         <option>tcrypt-keyfile=</option> to provide the absolute path
 313         to all key files. When using an empty passphrase in
 314         combination with one or more key files, use
 315         <literal>/dev/null</literal> as the password file in the third
 316         field.</para></listitem>
 317       </varlistentry>
 318
 319       <varlistentry>
 320         <term><option>tcrypt-hidden</option></term>
 321
 322         <listitem><para>Use the hidden TrueCrypt volume. This option
 323         implies <option>tcrypt</option>.</para>
 324
 325         <para>This will map the hidden volume that is inside of the
 326         volume provided in the second field. Please note that there is
 327         no protection for the hidden volume if the outer volume is
 328         mounted instead. See
 329         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 330         for more information on this limitation.</para></listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term><option>tcrypt-keyfile=</option></term>
 335
 336         <listitem><para>Specifies the absolute path to a key file to
 337         use for a TrueCrypt volume. This implies
 338         <option>tcrypt</option> and can be used more than once to
 339         provide several key files.</para>
 340
 341         <para>See the entry for <option>tcrypt</option> on the
 342         behavior of the passphrase and key files when using TrueCrypt
 343         encryption mode.</para></listitem>
 344       </varlistentry>
 345
 346       <varlistentry>
 347         <term><option>tcrypt-system</option></term>
 348
 349         <listitem><para>Use TrueCrypt in system encryption mode. This
 350         option implies <option>tcrypt</option>.</para></listitem>
 351       </varlistentry>
 352
 353       <varlistentry>
 354         <term><option>tcrypt-veracrypt</option></term>
 355
 356         <listitem><para>Check for a VeraCrypt volume.  VeraCrypt is a fork of
 357         TrueCrypt that is mostly compatible, but uses different, stronger key
 358         derivation algorithms that cannot be detected without this flag.
 359         Enabling this option could substantially slow down unlocking, because
 360         VeraCrypt's key derivation takes much longer than TrueCrypt's.  This
 361         option implies <option>tcrypt</option>.</para></listitem>
 362       </varlistentry>
 363
 364       <varlistentry>
 365         <term><option>timeout=</option></term>
 366
 367         <listitem><para>Specifies the timeout for querying for a
 368         password. If no unit is specified, seconds is used. Supported
 369         units are s, ms, us, min, h, d. A timeout of 0 waits
 370         indefinitely (which is the default).</para></listitem>
 371       </varlistentry>
 372
 373       <varlistentry>
 374         <term><option>tmp</option></term>
 375
 376         <listitem><para>The encrypted block device will be prepared
 377         for using it as <filename>/tmp</filename>; it will be
 378         formatted using
 379         <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 380         This option implies <option>plain</option>.</para>
 381
 382         <para>WARNING: Using the <option>tmp</option> option will
 383         destroy the contents of the named partition during every boot,
 384         so make sure the underlying block device is specified
 385         correctly.</para></listitem>
 386       </varlistentry>
 387
 388       <varlistentry>
 389         <term><option>tries=</option></term>
 390
 391         <listitem><para>Specifies the maximum number of times the user
 392         is queried for a password. The default is 3. If set to 0, the
 393         user is queried for a password indefinitely.</para></listitem>
 394       </varlistentry>
 395
 396       <varlistentry>
 397         <term><option>verify</option></term>
 398
 399         <listitem><para> If the encryption password is read from
 400         console, it has to be entered twice to prevent
 401         typos.</para></listitem>
 402       </varlistentry>
 403
 404       <varlistentry>
 405         <term><option>x-systemd.device-timeout=</option></term>
 406
 407         <listitem><para>Specifies how long systemd should wait for a device to show up
 408         before giving up on the entry. The argument is a time in seconds or explicitly
 409         specified units of
 410         <literal>s</literal>,
 411         <literal>min</literal>,
 412         <literal>h</literal>,
 413         <literal>ms</literal>.
 414         </para></listitem>
 415       </varlistentry>
 416
 417     </variablelist>
 418
 419     <para>At early boot and when the system manager configuration is
 420     reloaded, this file is translated into native systemd units by
 421     <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 422   </refsect1>
 423
 424   <refsect1>
 425     <title>Example</title>
 426     <example>
 427       <title>/etc/crypttab example</title>
 428       <para>Set up four encrypted block devices. One using LUKS for
 429       normal storage, another one for usage as a swap device and two
 430       TrueCrypt volumes.</para>
 431
 432       <programlisting>luks       UUID=2505567a-9e27-4efe-a4d5-15ad146c258b
 433 swap       /dev/sda7       /dev/urandom       swap
 434 truecrypt  /dev/sda2       /etc/container_password  tcrypt
 435 hidden     /mnt/tc_hidden  /dev/null    tcrypt-hidden,tcrypt-keyfile=/etc/keyfile</programlisting>
 436     </example>
 437   </refsect1>
 438
 439   <refsect1>
 440     <title>See Also</title>
 441     <para>
 442       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 443       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 444       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 445       <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 446       <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 447       <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 448       <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 449     </para>
 450   </refsect1>
 451
 452 </refentry>