3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5 This file is part of systemd.
7 Copyright 2012 Lennart Poettering
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.
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.
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/>.
22 This is based on crypttab(5) from Fedora's initscripts package, which in
23 turn is based on Debian's version.
25 The Red Hat version has been written by Miloslav Trmac <mitr@redhat.com>.
28 <refentry id="crypttab" conditional='HAVE_LIBCRYPTSETUP'>
31 <title>crypttab</title>
32 <productname>systemd</productname>
36 <contrib>Documentation</contrib>
37 <firstname>Miloslav</firstname>
38 <surname>Trmac</surname>
39 <email>mitr@redhat.com</email>
42 <contrib>Documentation</contrib>
43 <firstname>Lennart</firstname>
44 <surname>Poettering</surname>
45 <email>lennart@poettering.net</email>
51 <refentrytitle>crypttab</refentrytitle>
52 <manvolnum>5</manvolnum>
56 <refname>crypttab</refname>
57 <refpurpose>Configuration for encrypted block devices</refpurpose>
61 <para><filename>/etc/crypttab</filename></para>
65 <title>Description</title>
67 <para>The <filename>/etc/crypttab</filename> file
68 describes encrypted block devices that are set up
69 during system boot.</para>
71 <para>Empty lines and lines starting with the <literal>#</literal>
72 character are ignored. Each of the remaining lines
73 describes one encrypted block device, fields on the
74 line are delimited by white space. The first two
75 fields are mandatory, the remaining two are
78 <para>Setting up encrypted block devices using this file
79 supports three encryption modes: LUKS, TrueCrypt and plain.
80 See <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
81 for more information about each mode. When no mode is specified
82 in the options field and the block device contains a LUKS
83 signature, it is opened as a LUKS device; otherwise, it is
84 assumed to be in raw dm-crypt (plain mode) format.</para>
86 <para>The first field contains the name of the
87 resulting encrypted block device; the device is set up
88 within <filename>/dev/mapper/</filename>.</para>
90 <para>The second field contains a path to the
91 underlying block device or file, or a specification of a block
92 device via <literal>UUID=</literal> followed by the
95 <para>The third field specifies the encryption
96 password. If the field is not present or the password
97 is set to <literal>none</literal> or <literal>-</literal>,
98 the password has to be manually entered during system boot.
99 Otherwise, the field is interpreted as a absolute path to
100 a file containing the encryption password. For swap encryption,
101 <filename>/dev/urandom</filename> or the hardware
102 device <filename>/dev/hw_random</filename> can be used
103 as the password file; using
104 <filename>/dev/random</filename> may prevent boot
105 completion if the system does not have enough entropy
106 to generate a truly random encryption key.</para>
108 <para>The fourth field, if present, is a
109 comma-delimited list of options. The following
110 options are recognized:</para>
112 <variablelist class='crypttab-options'>
115 <term><varname>allow-discards</varname></term>
117 <listitem><para>Allow discard requests to be
118 passed through the encrypted block device. This
119 improves performance on SSD storage but has
120 security implications.</para></listitem>
124 <term><varname>cipher=</varname></term>
126 <listitem><para>Specifies the cipher to use. See
127 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
128 for possible values and the default value of
129 this option. A cipher with unpredictable IV
130 values, such as <literal>aes-cbc-essiv:sha256</literal>,
131 is recommended.</para></listitem>
135 <term><varname>hash=</varname></term>
137 <listitem><para>Specifies the hash to use for
138 password hashing. See
139 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
140 for possible values and the default value of
141 this option.</para></listitem>
145 <term><varname>keyfile-offset=</varname></term>
147 <listitem><para>Specifies the number of bytes to
148 skip at the start of the key file. See
149 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
150 for possible values and the default value of
151 this option.</para></listitem>
155 <term><varname>keyfile-size=</varname></term>
157 <listitem><para>Specifies the maximum number
158 of bytes to read from the key file. See
159 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
160 for possible values and the default value of
161 this option. This option is ignored in plain
162 encryption mode, as the key file size is then
163 given by the key size.</para></listitem>
167 <term><varname>luks</varname></term>
169 <listitem><para>Force LUKS mode. When this mode
170 is used, the following options are ignored since
171 they are provided by the LUKS header on the
172 device: <varname>cipher=</varname>,
173 <varname>hash=</varname>,
174 <varname>size=</varname>.</para></listitem>
178 <term><varname>noauto</varname></term>
180 <listitem><para>This device will not be
181 automatically unlocked on boot.</para></listitem>
185 <term><varname>nofail</varname></term>
187 <listitem><para>The system will not wait for the
188 device to show up and be unlocked at boot, and
189 not fail the boot if it does not show up.</para></listitem>
193 <term><varname>plain</varname></term>
195 <listitem><para>Force plain encryption mode.</para></listitem>
199 <term><varname>read-only</varname></term><term><varname>readonly</varname></term>
201 <listitem><para>Set up the encrypted block
202 device in read-only mode.</para></listitem>
206 <term><varname>size=</varname></term>
208 <listitem><para>Specifies the key size
210 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
211 for possible values and the default value of
212 this option.</para></listitem>
216 <term><varname>swap</varname></term>
218 <listitem><para>The encrypted block device will
219 be used as a swap device, and will be formatted
220 accordingly after setting up the encrypted
222 <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
223 This option implies <varname>plain</varname>.</para>
225 <para>WARNING: Using the <varname>swap</varname>
226 option will destroy the contents of the named
227 partition during every boot, so make sure the
228 underlying block device is specified correctly.</para></listitem>
232 <term><varname>tcrypt</varname></term>
234 <listitem><para>Use TrueCrypt encryption mode.
235 When this mode is used, the following options are
236 ignored since they are provided by the TrueCrypt
237 header on the device or do not apply:
238 <varname>cipher=</varname>,
239 <varname>hash=</varname>,
240 <varname>keyfile-offset=</varname>,
241 <varname>keyfile-size=</varname>,
242 <varname>size=</varname>.</para>
244 <para>When this mode is used, the passphrase is
245 read from the key file given in the third field.
246 Only the first line of this file is read,
247 excluding the new line character.</para>
249 <para>Note that the TrueCrypt format uses both
250 passphrase and key files to derive a password
251 for the volume. Therefore, the passphrase and
252 all key files need to be provided. Use
253 <varname>tcrypt-keyfile=</varname> to provide
254 the absolute path to all key files. When using
255 an empty passphrase in combination with one or
256 more key files, use <literal>/dev/null</literal>
257 as the password file in the third field.</para></listitem>
261 <term><varname>tcrypt-hidden</varname></term>
263 <listitem><para>Use the hidden TrueCrypt volume.
264 This implies <varname>tcrypt</varname>.</para>
266 <para>This will map the hidden volume that is
267 inside of the volume provided in the second
268 field. Please note that there is no protection
269 for the hidden volume if the outer volume is
271 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
272 for more information on this limitation.</para></listitem>
276 <term><varname>tcrypt-keyfile=</varname></term>
278 <listitem><para>Specifies the absolute path to a
279 key file to use for a TrueCrypt volume. This
280 implies <varname>tcrypt</varname> and can be
281 used more than once to provide several key
284 <para>See the entry for <varname>tcrypt</varname>
285 on the behavior of the passphrase and key files
286 when using TrueCrypt encryption mode.</para></listitem>
290 <term><varname>tcrypt-system</varname></term>
292 <listitem><para>Use TrueCrypt in system
293 encryption mode. This implies
294 <varname>tcrypt</varname>.</para>
296 <para>Please note that when using this mode, the
297 whole device needs to be given in the second
298 field instead of the partition. For example: if
299 <literal>/dev/sda2</literal> is the system
300 encrypted TrueCrypt patition, <literal>/dev/sda</literal>
301 has to be given.</para></listitem>
305 <term><varname>timeout=</varname></term>
307 <listitem><para>Specifies the timeout for
308 querying for a password. If no unit is
309 specified, seconds is used. Supported units are
310 s, ms, us, min, h, d. A timeout of 0 waits
311 indefinitely (which is the default).</para></listitem>
315 <term><varname>tmp</varname></term>
317 <listitem><para>The encrypted block device will
318 be prepared for using it as <filename>/tmp</filename>;
319 it will be formatted using
320 <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
321 This option implies <varname>plain</varname>.</para>
323 <para>WARNING: Using the <varname>tmp</varname>
324 option will destroy the contents of the named
325 partition during every boot, so make sure the
326 underlying block device is specified correctly.</para></listitem>
330 <term><varname>tries=</varname></term>
332 <listitem><para>Specifies the maximum number of
333 times the user is queried for a password.</para></listitem>
337 <term><varname>verify</varname></term>
339 <listitem><para> If the encryption password is
340 read from console, it has to be entered twice to
341 prevent typos.</para></listitem>
346 <para>At early boot and when the system manager
347 configuration is reloaded, this file is translated into
349 by <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
353 <title>Example</title>
355 <title>/etc/crypttab example</title>
356 <para>Set up four encrypted block devices. One using
357 LUKS for normal storage, another one for usage as a swap
358 device and two TrueCrypt volumes.</para>
360 <programlisting>luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b
361 swap /dev/sda7 /dev/urandom swap
362 truecrypt /dev/sda2 /etc/container_password tcrypt
363 hidden /mnt/tc_hidden /null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile</programlisting>
368 <title>See Also</title>
370 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
371 <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
372 <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
373 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
374 <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
375 <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>