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