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 project='die-net'><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 an 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 project='die-net'><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 project='die-net'><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 project='die-net'><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>offset=</option></term>
 150
 151         <listitem><para>Start offset in the backend device, in 512-byte sectors.
 152         This option is only relevant for plain devices.
 153         </para></listitem>
 154       </varlistentry>
 155
 156       <varlistentry>
 157         <term><option>skip=</option></term>
 158
 159         <listitem><para>How many 512-byte sectors of the encrypted data to skip
 160         at the beginning. This is different from the <option>--offset</option>
 161         option with respect to the sector numbers used in initialization vector
 162         (IV) calculation. Using <option>--offset</option> will shift the IV
 163         calculation by the same negative amount.  Hence, if <option>--offset n</option> is given,
 164         sector n will  get a sector number of 0 for the IV calculation.
 165         Using <option>--skip</option> causes sector n to also be the first
 166         sector of the mapped device, but with its number for IV generation being n.</para>
 167
 168         <para>This option is only relevant for plain devices.</para>
 169         </listitem>
 170       </varlistentry>
 171
 172       <varlistentry>
 173         <term><option>keyfile-offset=</option></term>
 174
 175         <listitem><para>Specifies the number of bytes to skip at the
 176         start of the key file. See
 177         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 178         for possible values and the default value of this
 179         option.</para></listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><option>keyfile-size=</option></term>
 184
 185         <listitem><para>Specifies the maximum number of bytes to read
 186         from the key file. See
 187         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 188         for possible values and the default value of this option. This
 189         option is ignored in plain encryption mode, as the key file
 190         size is then given by the key size.</para></listitem>
 191       </varlistentry>
 192
 193       <varlistentry>
 194         <term><option>key-slot=</option></term>
 195
 196         <listitem><para>Specifies the key slot to compare the
 197         passphrase or key against. If the key slot does not match the
 198         given passphrase or key, but another would, the setup of the
 199         device will fail regardless. This option implies
 200         <option>luks</option>. See
 201         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 202         for possible values. The default is to try all key slots in
 203         sequential order.</para></listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term><option>luks</option></term>
 208
 209         <listitem><para>Force LUKS mode. When this mode is used, the
 210         following options are ignored since they are provided by the
 211         LUKS header on the device: <option>cipher=</option>,
 212         <option>hash=</option>,
 213         <option>size=</option>.</para></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>plain</option></term>
 233
 234         <listitem><para>Force plain encryption mode.</para></listitem>
 235       </varlistentry>
 236
 237       <varlistentry>
 238         <term><option>read-only</option></term><term><option>readonly</option></term>
 239
 240         <listitem><para>Set up the encrypted block device in read-only
 241         mode.</para></listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term><option>size=</option></term>
 246
 247         <listitem><para>Specifies the key size in bits. See
 248         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 249         for possible values and the default value of this
 250         option.</para></listitem>
 251       </varlistentry>
 252
 253       <varlistentry>
 254         <term><option>swap</option></term>
 255
 256         <listitem><para>The encrypted block device will be used as a
 257         swap device, and will be formatted accordingly after setting
 258         up the encrypted block device, with
 259         <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 260         This option implies <option>plain</option>.</para>
 261
 262         <para>WARNING: Using the <option>swap</option> option will
 263         destroy the contents of the named partition during every boot,
 264         so make sure the underlying block device is specified
 265         correctly.</para></listitem>
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term><option>tcrypt</option></term>
 270
 271         <listitem><para>Use TrueCrypt encryption mode. When this mode
 272         is used, the following options are ignored since they are
 273         provided by the TrueCrypt header on the device or do not
 274         apply:
 275         <option>cipher=</option>,
 276         <option>hash=</option>,
 277         <option>keyfile-offset=</option>,
 278         <option>keyfile-size=</option>,
 279         <option>size=</option>.</para>
 280
 281         <para>When this mode is used, the passphrase is read from the
 282         key file given in the third field. Only the first line of this
 283         file is read, excluding the new line character.</para>
 284
 285         <para>Note that the TrueCrypt format uses both passphrase and
 286         key files to derive a password for the volume. Therefore, the
 287         passphrase and all key files need to be provided. Use
 288         <option>tcrypt-keyfile=</option> to provide the absolute path
 289         to all key files. When using an empty passphrase in
 290         combination with one or more key files, use
 291         <literal>/dev/null</literal> as the password file in the third
 292         field.</para></listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term><option>tcrypt-hidden</option></term>
 297
 298         <listitem><para>Use the hidden TrueCrypt volume. This option
 299         implies <option>tcrypt</option>.</para>
 300
 301         <para>This will map the hidden volume that is inside of the
 302         volume provided in the second field. Please note that there is
 303         no protection for the hidden volume if the outer volume is
 304         mounted instead. See
 305         <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 306         for more information on this limitation.</para></listitem>
 307       </varlistentry>
 308
 309       <varlistentry>
 310         <term><option>tcrypt-keyfile=</option></term>
 311
 312         <listitem><para>Specifies the absolute path to a key file to
 313         use for a TrueCrypt volume. This implies
 314         <option>tcrypt</option> and can be used more than once to
 315         provide several key files.</para>
 316
 317         <para>See the entry for <option>tcrypt</option> on the
 318         behavior of the passphrase and key files when using TrueCrypt
 319         encryption mode.</para></listitem>
 320       </varlistentry>
 321
 322       <varlistentry>
 323         <term><option>tcrypt-system</option></term>
 324
 325         <listitem><para>Use TrueCrypt in system encryption mode. This
 326         option implies <option>tcrypt</option>.</para></listitem>
 327       </varlistentry>
 328
 329       <varlistentry>
 330         <term><option>timeout=</option></term>
 331
 332         <listitem><para>Specifies the timeout for querying for a
 333         password. If no unit is specified, seconds is used. Supported
 334         units are s, ms, us, min, h, d. A timeout of 0 waits
 335         indefinitely (which is the default).</para></listitem>
 336       </varlistentry>
 337
 338       <varlistentry>
 339         <term><option>x-systemd.device-timeout=</option></term>
 340
 341         <listitem><para>Specifies how long systemd should wait for a
 342         device to show up before giving up on the entry. The argument
 343         is a time in seconds or explicitly specified units of
 344         <literal>s</literal>,
 345         <literal>min</literal>,
 346         <literal>h</literal>,
 347         <literal>ms</literal>.
 348         </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     </variablelist>
 383
 384     <para>At early boot and when the system manager configuration is
 385     reloaded, this file is translated into native systemd units by
 386     <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 387   </refsect1>
 388
 389   <refsect1>
 390     <title>Example</title>
 391     <example>
 392       <title>/etc/crypttab example</title>
 393       <para>Set up four encrypted block devices. One using LUKS for
 394       normal storage, another one for usage as a swap device and two
 395       TrueCrypt volumes.</para>
 396
 397       <programlisting>luks       UUID=2505567a-9e27-4efe-a4d5-15ad146c258b
 398 swap       /dev/sda7       /dev/urandom       swap
 399 truecrypt  /dev/sda2       /etc/container_password  tcrypt
 400 hidden     /mnt/tc_hidden  /dev/null    tcrypt-hidden,tcrypt-keyfile=/etc/keyfile</programlisting>
 401     </example>
 402   </refsect1>
 403
 404   <refsect1>
 405     <title>See Also</title>
 406     <para>
 407       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 408       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 409       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 410       <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 411       <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 412       <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 413     </para>
 414   </refsect1>
 415
 416 </refentry>