mirror of
https://github.com/systemd/systemd-stable.git
synced 2024-12-27 03:21:32 +03:00
1acbb95c2b
systemd-cryptsetup recognizes option 'allow-discards' in /etc/crypttab to enable TRIM passthrough to underlying encrypted device. In Debian this option was changed to 'discard' to avoid hyphen in option name. (see: #648868 and `man crypttab`). [zj: update crypttab(5) too, making "discard" the default.]
380 lines
20 KiB
XML
380 lines
20 KiB
XML
<?xml version="1.0"?>
|
|
<!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
<!--
|
|
This file is part of systemd.
|
|
|
|
Copyright 2012 Lennart Poettering
|
|
|
|
systemd is free software; you can redistribute it and/or modify it
|
|
under the terms of the GNU Lesser General Public License as published by
|
|
the Free Software Foundation; either version 2.1 of the License, or
|
|
(at your option) any later version.
|
|
|
|
systemd is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public License
|
|
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
This is based on crypttab(5) from Fedora's initscripts package, which in
|
|
turn is based on Debian's version.
|
|
|
|
The Red Hat version has been written by Miloslav Trmac <mitr@redhat.com>.
|
|
|
|
-->
|
|
<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='crypttab-options'>
|
|
|
|
<varlistentry>
|
|
<term><varname>discard</varname></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><varname>cipher=</varname></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><varname>hash=</varname></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><varname>keyfile-offset=</varname></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><varname>keyfile-size=</varname></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><varname>luks</varname></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: <varname>cipher=</varname>,
|
|
<varname>hash=</varname>,
|
|
<varname>size=</varname>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>noauto</varname></term>
|
|
|
|
<listitem><para>This device will not be
|
|
automatically unlocked on boot.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>nofail</varname></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><varname>plain</varname></term>
|
|
|
|
<listitem><para>Force plain encryption mode.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>read-only</varname></term><term><varname>readonly</varname></term>
|
|
|
|
<listitem><para>Set up the encrypted block
|
|
device in read-only mode.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>size=</varname></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><varname>swap</varname></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><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
|
|
This option implies <varname>plain</varname>.</para>
|
|
|
|
<para>WARNING: Using the <varname>swap</varname>
|
|
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><varname>tcrypt</varname></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:
|
|
<varname>cipher=</varname>,
|
|
<varname>hash=</varname>,
|
|
<varname>keyfile-offset=</varname>,
|
|
<varname>keyfile-size=</varname>,
|
|
<varname>size=</varname>.</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
|
|
<varname>tcrypt-keyfile=</varname> 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><varname>tcrypt-hidden</varname></term>
|
|
|
|
<listitem><para>Use the hidden TrueCrypt volume.
|
|
This implies <varname>tcrypt</varname>.</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><varname>tcrypt-keyfile=</varname></term>
|
|
|
|
<listitem><para>Specifies the absolute path to a
|
|
key file to use for a TrueCrypt volume. This
|
|
implies <varname>tcrypt</varname> and can be
|
|
used more than once to provide several key
|
|
files.</para>
|
|
|
|
<para>See the entry for <varname>tcrypt</varname>
|
|
on the behavior of the passphrase and key files
|
|
when using TrueCrypt encryption mode.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>tcrypt-system</varname></term>
|
|
|
|
<listitem><para>Use TrueCrypt in system
|
|
encryption mode. This implies
|
|
<varname>tcrypt</varname>.</para>
|
|
|
|
<para>Please note that when using this mode, the
|
|
whole device needs to be given in the second
|
|
field instead of the partition. For example: if
|
|
<literal>/dev/sda2</literal> is the system
|
|
encrypted TrueCrypt patition, <literal>/dev/sda</literal>
|
|
has to be given.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>timeout=</varname></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><varname>tmp</varname></term>
|
|
|
|
<listitem><para>The encrypted block device will
|
|
be prepared for using it as <filename>/tmp</filename>;
|
|
it will be formatted using
|
|
<citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
|
|
This option implies <varname>plain</varname>.</para>
|
|
|
|
<para>WARNING: Using the <varname>tmp</varname>
|
|
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><varname>tries=</varname></term>
|
|
|
|
<listitem><para>Specifies the maximum number of
|
|
times the user is queried for a password.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>verify</varname></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 /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><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|