<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd">

<refentry id="file.crypttab">

 <xi:include href="variables.xml"
             xpointer="xpointer(/refentry/refentryinfo)"
             xmlns:xi="http://www.w3.org/2001/XInclude"/>

 <refmeta>
  <refentrytitle>crypttab</refentrytitle>
  <manvolnum>5</manvolnum>
  <xi:include href="variables.xml"
              xpointer="xpointer(/refentry/refmeta/*)"
	      xmlns:xi="http://www.w3.org/2001/XInclude"/>
 </refmeta>

 <refnamediv>
  <refname>crypttab</refname>
  <refpurpose>static information about encrypted filesystems</refpurpose>
 </refnamediv>

 <refsect1 id="crypttab.description">
  <title>DESCRIPTION</title>
  <simpara>
   The file <filename>/etc/crypttab</filename> contains descriptive
   information about encrypted filesystems. <filename>crypttab</filename>
   is only read by programs (e.g.
   <command moreinfo="refentry">cryptdisks_start</command> and
   <command moreinfo="refentry">cryptdisks_stop</command>),
   and not written; it is the duty of the system
   administrator to properly create and maintain this file. Each filesystem is
   described on a separate line; fields on each line are separated by tabs or
   spaces. Lines starting with <quote>#</quote> are comments, empty lines are 
   ignored. The order of records in <filename>crypttab</filename> is important
   because the init scripts sequentially iterate through 
   <filename>crypttab</filename> doing their thing.
  </simpara>
  <simpara>
   The first field, <emphasis>target</emphasis>, describes the mapped
   device name. It must be a plain filename without any directory components.
   A mapped device which encrypts/decrypts data to/from the <emphasis>source
   device</emphasis> will be created at
   <filename class="devicefile">/dev/mapper/target</filename> by
   <command moreinfo="refentry">cryptsetup</command>.
  </simpara>
  <simpara>
   The second field, <emphasis>source device</emphasis>, describes either the
   block special device or file that contains the encrypted data. Instead of
   giving the <emphasis>source device</emphasis> explicitly, the UUID is
   supported as well, using <emphasis>UUID=&lt;luks_uuid&gt;</emphasis>.
  </simpara>
  <simpara>
   The third field, <emphasis>key file</emphasis>, describes the file to use
   as a key for decrypting the data of the <emphasis>source device</emphasis>.
   Note that the <emphasis>entire</emphasis> key file will be used as the
   passphrase; the passphrase must <emphasis>not</emphasis> be
   followed by a newline character.
  </simpara>
  <simpara>
   It can also be a device name (e.g.
   <filename class="devicefile">/dev/urandom</filename>), note however that
   LUKS requires a persistent key and therefore does <emphasis>not</emphasis>
   support random data keys.
  </simpara>
  <simpara>
   If the <emphasis>key file</emphasis> is the string <quote>none</quote>, 
   a passphrase will be read interactively from the console. In this case, the
   options precheck, check, checkargs and tries may be useful.
  </simpara>
  <simpara>
   The fourth field, <emphasis>options</emphasis>, describes the cryptsetup
   options associated with the encryption process. At minimum, the field should
   contain either the string <emphasis>luks</emphasis> or the
   <emphasis>cipher</emphasis>, <emphasis>hash</emphasis> and
   <emphasis>size</emphasis> options.
  </simpara>
  <simpara>
   Options are in the format: <emphasis>key</emphasis>=<emphasis>value</emphasis>
   [,<emphasis>key</emphasis>=<emphasis>value</emphasis> &#8230;]. The
   supported options are described below.
  </simpara>
  <simpara>
   Note that all four fields are mandatory and that a missing field will lead
   to unspecified behaviour.
  </simpara>
 </refsect1>

 <refsect1 id="crypttab.options">
  <title>OPTIONS</title>
  <variablelist>

   <varlistentry>
    <term><emphasis>cipher</emphasis>=&lt;cipher&gt;</term>
    <listitem>
     <simpara>
      Encryption algorithm (ignored for LUKS devices). See <command>cryptsetup -c</command>.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>size</emphasis>=&lt;size&gt;</term>
    <listitem>
     <simpara>
      Encryption key size (ignored for LUKS devices). See <command>cryptsetup -s</command>.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>hash</emphasis>=&lt;hash&gt;</term>
    <listitem>
     <simpara>
      Hash algorithm (ignored for LUKS devices). See <command>cryptsetup -h</command>.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>offset</emphasis>=&lt;offset&gt;</term>
    <listitem>
     <simpara>
      Start offset (ignored for LUKS devices). Uses <emphasis role="strong">cryptsetup -o</emphasis>.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>skip</emphasis>=&lt;skip&gt;</term>
    <listitem>
     <simpara>
      Skip sectors at the beginning (ignored for LUKS devices). Uses <emphasis role="strong">cryptsetup -p</emphasis>.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>verify</emphasis></term>
    <listitem>
     <simpara>
      Verify password. Uses <emphasis role="strong">cryptsetup -y</emphasis>.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>readonly</emphasis></term>
    <listitem>
     <simpara>The backing device is read-only (eg: a dvd).</simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>discard</emphasis></term>
    <listitem>
     <simpara>Allow using of discards (TRIM) requests for device.</simpara>
     <simpara><emphasis role="strong">WARNING</emphasis>: Assess the
     specific security risks carefully before enabling this option.
     For example, allowing discards on encrypted devices may lead to
     the leak of information about the ciphertext device (filesystem
     type, used space etc.) if the discarded blocks can be located
     easily on the device later.</simpara>
      <simpara>Kernel version 3.1 or more recent is required.
      For older versions is the option ignored.</simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>luks</emphasis></term>
    <listitem>
     <simpara>Use device with LUKS extensions.</simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>swap</emphasis></term>
    <listitem>
     <simpara>
      Run <command moreinfo="refentry">mkswap</command> on the created device.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>tmp</emphasis>=&lt;tmpfs&gt;</term>
    <listitem>
     <simpara>
      Run <command moreinfo="refentry">mkfs</command> with filesystem type
      &lt;tmpfs&gt; on the created device. Default is ext4.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>precheck</emphasis>=&lt;precheck&gt;</term>
    <listitem>
     <simpara>Check the content of the source device by a suitable program; if
      the check fails, the device is not created. If a program is provided as an
      argument, it is run, giving the source device as argument.
      Cryptdisks/cryptroot searches for the given progam in
      <filename class="directory">/lib/cryptsetup/checks/</filename> first, but
      full path to program is supported as well.
     </simpara>
     <simpara>
      Prechecks aren't invoked for LUKS devices, as these are checked with isLuks
      anyway. Default for plain dm-crypt devices is set in
      <filename>/etc/default/cryptdisks</filename>, or <filename>un_blkid</filename>
      otherwise. Set to <filename>/bin/true</filename> in order to disable
      precheck for plain dm-crypt device.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>check</emphasis>=&lt;check&gt;</term>
    <listitem>
     <simpara>Check the content of the target device by a suitable program; if
      the check fails, the device is removed. If a program is provided as an
      argument, it is run, giving the decrypted volume (target device) as
      first argument, and the value of the checkargs option as second argument.
      Cryptdisks/cryptroot searches for the given program in
      <filename class="directory">/lib/cryptsetup/checks/</filename> first, but
      full path to program is supported as well.
     </simpara>
     <simpara>
      Default is set in <filename>/etc/default/cryptdisks</filename>
      (<filename>blkid</filename>).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>checkargs</emphasis>=&lt;arguments&gt;</term>
    <listitem>
     <simpara>Give &lt;arguments&gt; as the second argument to the check
      script. See the CHECKSCRIPTS section for more information.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>tries</emphasis>=&lt;num&gt;</term>
    <listitem>
     <simpara>The input of the passphrase is tried &lt;num&gt; times in case
      of failure. If you want to disable retries, pass <quote>tries=1</quote>.
      Default is 3. Setting <quote>tries=0</quote> will ask for the passphrase
      until a correct one has been submitted (infinitive retries).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>noearly</emphasis></term>
    <listitem>
     <simpara>The cryptsetup init scripts are invoked twice during the boot 
      process - once before lvm, evms, raid, etc. are started and once again
      after that. Sometimes you need to start your encrypted disks in a special
      order. With this option the device is ignored during the first invokation
      of the cryptsetup init scripts.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>noauto</emphasis></term>
    <listitem>
     <simpara>Entirely ignore the device at the boot process. It's still
      possible to map the device manually using cryptdisks_start.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>loud</emphasis></term>
    <listitem>
     <simpara>Be loud. Print warnings if a device does not exist.
     This option overwrites the option <emphasis>quiet</emphasis>.</simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>quiet</emphasis></term>
    <listitem>
     <simpara>Be quiet. Don't print warnings if a device does not exist.
     This option overwrites the option <emphasis>loud</emphasis>.</simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>keyscript</emphasis>=&lt;path&gt;</term>
    <listitem>
     <simpara>
      The executable at the indicated path is executed with the
      <emphasis>key file</emphasis> from the third field of the crypttab as its
      only argument and the output is used as the key. This also works with
      encrypted root filesystems via initramfs if the executable is
      self-contained (i.e. an executable which does not rely on any external
      program which is not present in the initramfs environment).
     </simpara>
     <simpara>
      LIMITATIONS: All binaries and files on which the keyscript depends must
      be available at the time of execution. Special care needs to be taken for
      encrypted filesystems like /usr or /var. As an example, unlocking
      encrypted /usr must not depend on binaries from /usr/(s)bin.
     </simpara>
     <para>
      All fields of the appropriate crypttab entry are available to the keyscript
      as exported environment variables:
      <variablelist>

       <varlistentry>
        <term>CRYPTTAB_NAME</term>
        <listitem><para>
	 The target name
        </para></listitem>
       </varlistentry>
       <varlistentry>
        <term>CRYPTTAB_SOURCE</term>
        <listitem><para>
	 The source device
        </para></listitem>
       </varlistentry>
       <varlistentry>
        <term>CRYPTTAB_KEY</term>
        <listitem><para>
	 The key file
        </para></listitem>
       </varlistentry>
       <varlistentry>
        <term>CRYPTTAB_OPTIONS</term>
        <listitem><para>
	 A list of exported crypttab options
        </para></listitem>
       </varlistentry>
       <varlistentry>
        <term>CRYPTTAB_OPTION_&lt;option&gt;</term>
        <listitem><para>
	 The value of the appropriate crypttab option, with value set to 'yes'
         in case the option is merely a flag.
        </para></listitem>
       </varlistentry>

      </variablelist>
     </para>
    </listitem>
   </varlistentry>

  </variablelist>
 </refsect1>

 <refsect1 id="crypttab.checkscripts">
  <title>CHECKSCRIPTS</title>
  <variablelist>

   <varlistentry>
    <term><emphasis>blkid</emphasis></term>
    <listitem>
     <simpara>Checks for any known filesystem. Supports a filesystem type as
      argument via &lt;checkargs&gt;:
     </simpara>
     <itemizedlist>
      <listitem><para>
       no checkargs - succeeds if any valid filesystem is found on the device.
      </para></listitem>
      <listitem><para>
       "none" - succeeds if no valid filesystem is found on the device.
      </para></listitem>
      <listitem><para>
       "ext4" [or another filesystem type like xfs, swap, crypto_LUKS, ...] -
       succeeds if ext4 filesystem is found on the device.
      </para></listitem>
     </itemizedlist>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>un_blkid</emphasis></term>
    <listitem>
     <simpara>Checks for no known filesystem. Supports a filesystem type as
      argument via &lt;checkargs&gt;:
     </simpara>
     <itemizedlist>
      <listitem><para>
       no checkargs - succeeds if no valid filesystem is found on the device.
      </para></listitem>
      <listitem><para>
       "ext4" [or another filesystem type like xfs, swap, crypto_LUKS, ...] -
       succeeds if no ext4 filesystem is found on the device.
      </para></listitem>
     </itemizedlist>
    </listitem>
   </varlistentry>

  </variablelist>
 </refsect1>

 <refsect1 id="crypttab.examples">
  <title>EXAMPLES</title>
  <para>
   <screen>
# Encrypted swap device
cswap /dev/sda6 /dev/urandom cipher=aes-cbc-essiv:sha256,hash=ripemd160,size=256,swap
    
# Encrypted LUKS disk with interactive password, identified by UUID
cdisk0 UUID=12345678-9abc-def012345-6789abcdef01 none luks
    
# Encrypted ext4 disk with interactive password
# - retry 5 times if the check fails
cdisk1 /dev/sda2 none cipher=aes-cbc-essiv:sha256,hash=ripemd160,size=256,checkargs=ext4,tries=5

# Encrypted disk with interactive password
# - use a nondefault check script
# - no retries
cdisk2 /dev/hdc1 none cipher=aes-cbc-essiv:sha256,hash=ripemd160,size=256,check=customscript,tries=1

# Encrypted disk with interactive password
# - twofish as the cipher
cdisk3 /dev/sda3 none cipher=twofish,hash=ripemd160,size=256
   </screen>
  </para>
 </refsect1>

 <refsect1 id="crypttab.environment">
  <title>ENVIRONMENT</title>
  <variablelist>

   <varlistentry>
    <term><emphasis>CRYPTDISKS_ENABLE</emphasis></term>
    <listitem>
     <simpara>
      Set to <emphasis>yes</emphasis> to run cryptdisks initscripts at startup.
      Set to <emphasis>no</emphasis> to disable cryptdisks initscripts. Default
      is <emphasis>yes</emphasis>.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>CRYPTDISKS_MOUNT</emphasis></term>
    <listitem>
     <simpara>Specifies the mountpoints that are mounted before cryptdisks is
      invoked. Takes mountpoints configured in /etc/fstab as arguments. Separate
      mountpoints by space.
      This is useful for keys on removable devices, such as cdrom, usbstick,
      flashcard, etc. Default is unset.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>CRYPTDISKS_CHECK</emphasis></term>
    <listitem>
     <simpara>Specifies the default checkscript to be run against the target
      device, after cryptdisks has been invoked. The target device is passed as
      the first and only argument to the checkscript. Takes effect if the
      <emphasis>check</emphasis> option is given in crypttab with no value. See
      documentation for <emphasis>check</emphasis> option above for more
      information.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><emphasis>CRYPTDISKS_PRECHECK</emphasis></term>
    <listitem>
     <simpara>Specifies the default checkscript to be run against the source
      dm-crypt device, before cryptdisks has been invoked. The source device
      is given as the first and only argument to the checkscript. Takes effect
      if the <emphasis>precheck</emphasis> option is given in crypttab with no
      value. See documentation for <emphasis>precheck</emphasis> option above
      for more information.
     </simpara>
    </listitem>
   </varlistentry>

  </variablelist>
 </refsect1>

 <refsect1 id="crypttab.known_upgrade_issues">
  <title>KNOWN UPGRADE ISSUES</title>
  <simpara>
   The upstream defaults for encryption cipher, hash and keysize have changed
   several times in the past, and they're expected to change again in future,
   for example if security issues arise.

   On LUKS devices, the used settings are stored in the LUKS header, and thus
   don't need to be configured in <filename>/etc/crypttab</filename>. For plain
   dm-crypt devices, no information about used cipher, hash and keysize are
   available at all.

   Therefore we strongly suggest to configure the cipher, hash and keysize in
   <filename>/etc/crypttab</filename> for plain dm-crypt devices, even if they
   match the current default.
  </simpara>
 </refsect1>

 <refsect1 id="crypttab.see_also">
  <title>SEE ALSO</title>
  <simplelist type="inline">
   <member><command moreinfo="refentry">cryptsetup</command>(8)</member>
   <member><command moreinfo="refentry">cryptdisks_start</command>(8)</member>
   <member><command moreinfo="refentry">cryptdisks_stop</command>(8)</member>
  </simplelist>
 </refsect1>

 <refsect1 id="crypttab.author">
  <title>AUTHOR</title>
  <simpara>
   This manual page was originally written by
   <author>
    <firstname>Bastian</firstname>
    <surname>Kleineidam</surname>
   </author>
   <email>calvin@debian.org</email>
   for the Debian distribution of cryptsetup. It has been further improved by
   <author>
    <firstname>Michael</firstname>
    <surname>Gebetsroither</surname>
   </author>
   <email>michael.geb@gmx.at</email>,
   <author>
    <firstname>Jonas</firstname>
    <surname>Meurer</surname>
   </author>
   <email>jonas@freesources.org</email>
   and
   <author>
    <firstname>David</firstname>
    <surname>Härdeman</surname>
   </author>
   <email>david@hardeman.nu</email>.
  </simpara>
 </refsect1>

</refentry>