<?xml version="1.0"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="crypttab" conditional='HAVE_LIBCRYPTSETUP'>

<refentryinfo>

<title>crypttab</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Documentation</contrib>

<firstname>Miloslav</firstname>

<surname>Trmac</surname>

<email>mitr@redhat.com</email>

</author>

<author>

<contrib>Documentation</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>crypttab</refentrytitle>

<manvolnum>5</manvolnum>

</refmeta>

<refnamediv>

<refname>crypttab</refname>

<refpurpose>Configuration for encrypted block devices</refpurpose>

</refnamediv>

<refsynopsisdiv>

<para><filename>/etc/crypttab</filename></para>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>The <filename>/etc/crypttab</filename> file

describes encrypted block devices that are set up

during system boot.</para>

<para>Empty lines and lines starting with the <literal>#</literal>

character are ignored. Each of the remaining lines

describes one encrypted block device, fields on the

line are delimited by white space. The first two

fields are mandatory, the remaining two are

optional.</para>

<para>Setting up encrypted block devices using this file

supports three encryption modes: LUKS, TrueCrypt and plain.

See <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>

for more information about each mode. When no mode is specified

in the options field and the block device contains a LUKS

signature, it is opened as a LUKS device; otherwise, it is

assumed to be in raw dm-crypt (plain mode) format.</para>

<para>The first field contains the name of the

resulting encrypted block device; the device is set up

within <filename>/dev/mapper/</filename>.</para>

<para>The second field contains a path to the

underlying block device or file, or a specification of a block

device via <literal>UUID=</literal> followed by the

UUID.</para>

<para>The third field specifies the encryption

password. If the field is not present or the password

is set to <literal>none</literal> or <literal>-</literal>,

the password has to be manually entered during system boot.

Otherwise, the field is interpreted as a absolute path to

a file containing the encryption password. For swap encryption,

<filename>/dev/urandom</filename> or the hardware

device <filename>/dev/hw_random</filename> can be used

as the password file; using

<filename>/dev/random</filename> may prevent boot

completion if the system does not have enough entropy

to generate a truly random encryption key.</para>

<para>The fourth field, if present, is a

comma-delimited list of options. The following

options are recognized:</para>

<variablelist class='fstab-options'>

<varlistentry>

<term><option>discard</option></term>

<listitem><para>Allow discard requests to be

passed through the encrypted block device. This

improves performance on SSD storage but has

security implications.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>cipher=</option></term>

<listitem><para>Specifies the cipher to use. See

<citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>

for possible values and the default value of

this option. A cipher with unpredictable IV

values, such as <literal>aes-cbc-essiv:sha256</literal>,

is recommended.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>hash=</option></term>

<listitem><para>Specifies the hash to use for

password hashing. See

<citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>

for possible values and the default value of

this option.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>keyfile-offset=</option></term>

<listitem><para>Specifies the number of bytes to

skip at the start of the key file. See

<citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>

for possible values and the default value of

this option.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>keyfile-size=</option></term>

<listitem><para>Specifies the maximum number

of bytes to read from the key file. See

<citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>

for possible values and the default value of

this option. This option is ignored in plain

encryption mode, as the key file size is then

given by the key size.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>key-slot=</option></term>

<listitem><para>Specifies the key slot to

compare the passphrase or key against.

If the key slot does not match the given

passphrase or key, but another would, the

setup of the device will fail regardless.

This option implies <option>luks</option>. See

<citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>

for possible values. The default is to try

all key slots in sequential order.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>luks</option></term>

<listitem><para>Force LUKS mode. When this mode

is used, the following options are ignored since

they are provided by the LUKS header on the

device: <option>cipher=</option>,

<option>hash=</option>,

<option>size=</option>.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>noauto</option></term>

<listitem><para>This device will not be

automatically unlocked on boot.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>nofail</option></term>

<listitem><para>The system will not wait for the

device to show up and be unlocked at boot, and

not fail the boot if it does not show up.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>plain</option></term>

<listitem><para>Force plain encryption mode.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>read-only</option></term><term><option>readonly</option></term>

<listitem><para>Set up the encrypted block

device in read-only mode.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>size=</option></term>

<listitem><para>Specifies the key size

in bits. See

<citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>

for possible values and the default value of

this option.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>swap</option></term>

<listitem><para>The encrypted block device will

be used as a swap device, and will be formatted

accordingly after setting up the encrypted

block device, with

<citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.

This option implies <option>plain</option>.</para>

<para>WARNING: Using the <option>swap</option>

option will destroy the contents of the named

partition during every boot, so make sure the

underlying block device is specified correctly.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>tcrypt</option></term>

<listitem><para>Use TrueCrypt encryption mode.

When this mode is used, the following options are

ignored since they are provided by the TrueCrypt

header on the device or do not apply:

<option>cipher=</option>,

<option>hash=</option>,

<option>keyfile-offset=</option>,

<option>keyfile-size=</option>,

<option>size=</option>.</para>

<para>When this mode is used, the passphrase is

read from the key file given in the third field.

Only the first line of this file is read,

excluding the new line character.</para>

<para>Note that the TrueCrypt format uses both

passphrase and key files to derive a password

for the volume. Therefore, the passphrase and

all key files need to be provided. Use

<option>tcrypt-keyfile=</option> to provide

the absolute path to all key files. When using

an empty passphrase in combination with one or

more key files, use <literal>/dev/null</literal>

as the password file in the third field.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>tcrypt-hidden</option></term>

<listitem><para>Use the hidden TrueCrypt volume.

This option implies <option>tcrypt</option>.</para>

<para>This will map the hidden volume that is

inside of the volume provided in the second

field. Please note that there is no protection

for the hidden volume if the outer volume is

mounted instead. See

<citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>

for more information on this limitation.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>tcrypt-keyfile=</option></term>

<listitem><para>Specifies the absolute path to a

key file to use for a TrueCrypt volume. This

implies <option>tcrypt</option> and can be

used more than once to provide several key

files.</para>

<para>See the entry for <option>tcrypt</option>

on the behavior of the passphrase and key files

when using TrueCrypt encryption mode.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>tcrypt-system</option></term>

<listitem><para>Use TrueCrypt in system

encryption mode. This option implies

<option>tcrypt</option>.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>timeout=</option></term>

<listitem><para>Specifies the timeout for

querying for a password. If no unit is

specified, seconds is used. Supported units are

s, ms, us, min, h, d. A timeout of 0 waits

indefinitely (which is the default).</para></listitem>

</varlistentry>

<varlistentry>

<term><option>tmp</option></term>

<listitem><para>The encrypted block device will

be prepared for using it as <filename>/tmp</filename>;

it will be formatted using

<citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.

This option implies <option>plain</option>.</para>

<para>WARNING: Using the <option>tmp</option>

option will destroy the contents of the named

partition during every boot, so make sure the

underlying block device is specified correctly.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>tries=</option></term>

<listitem><para>Specifies the maximum number of

times the user is queried for a password.

The default is 3. If set to 0, the user is

queried for a password indefinitely.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>verify</option></term>

<listitem><para> If the encryption password is

read from console, it has to be entered twice to

prevent typos.</para></listitem>

</varlistentry>

</variablelist>

<para>At early boot and when the system manager

configuration is reloaded, this file is translated into

native systemd units

by <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>

</refsect1>

<refsect1>

<title>Example</title>

<example>

<title>/etc/crypttab example</title>

<para>Set up four encrypted block devices. One using

LUKS for normal storage, another one for usage as a swap

device and two TrueCrypt volumes.</para>

<programlisting>luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b

swap /dev/sda7 /dev/urandom swap

truecrypt /dev/sda2 /etc/container_password tcrypt

hidden /mnt/tc_hidden /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile</programlisting>

</example>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

<citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

<citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

<citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>