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">
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 #
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>The first field contains the name of the
79 resulting encrypted block device; the device is set up
80 within <filename>/dev/mapper/</filename>.</para>
82 <para>The second field contains a path to the
83 underlying block device, or a specification of a block
84 device via <literal>UUID=</literal> followed by the
85 UUID. If the block device contains a LUKS signature,
86 it is opened as a LUKS encrypted partition; otherwise
87 it is assumed to be a raw dm-crypt partition.</para>
89 <para>The third field specifies the encryption
90 password. If the field is not present or the password
91 is set to none, the password has to be manually
92 entered during system boot. Otherwise the field is
93 interpreted as a path to a file containing the
94 encryption password. For swap encryption
95 <filename>/dev/urandom</filename> or the hardware
96 device <filename>/dev/hw_random</filename> can be used
97 as the password file; using
98 <filename>/dev/random</filename> may prevent boot
99 completion if the system does not have enough entropy
100 to generate a truly random encryption key.</para>
102 <para>The fourth field, if present, is a
103 comma-delimited list of options. The following
104 options are recognized:</para>
106 <variablelist class='crypttab-options'>
108 <term><varname>cipher=</varname></term>
110 <listitem><para>Specifies the cipher
112 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
113 for possible values and the default
114 value of this option. A cipher with
115 unpredictable IV values, such as
116 <literal>aes-cbc-essiv:sha256</literal>,
117 is recommended. </para></listitem>
122 <term><varname>size=</varname></term>
124 <listitem><para>Specifies the key size
126 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
127 for possible values and the default
129 option. </para></listitem>
134 <term><varname>keyfile-size=</varname></term>
136 <listitem><para>Specifies the maximum number
137 of bytes to read from the keyfile; see
138 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
139 for possible values and the default
140 value of this option. This option is ignored
141 in plain encryption mode, as the keyfile-size is then given by the key size.</para></listitem>
146 <term><varname>keyfile-offset=</varname></term>
148 <listitem><para>Specifies the number
149 of bytes to skip at the start of
151 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
152 for possible values and the default
153 value of this option.</para></listitem>
158 <term><varname>hash=</varname></term>
160 <listitem><para>Specifies the hash to
161 use for password hashing; see
162 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for possible values and
163 the default value of this
164 option. </para></listitem>
168 <term><varname>tries=</varname></term>
170 <listitem><para>Specifies the maximum
171 number of times the user is queried
172 for a password.</para></listitem>
176 <term><varname>verify</varname></term>
178 <listitem><para> If the encryption
179 password is read from console, it has
180 to be entered twice (to prevent
181 typos). </para></listitem>
185 <term><varname>read-only</varname></term>
187 <listitem><para>Set up the encrypted
188 block device in read-only
189 mode.</para></listitem>
193 <term><varname>allow-discards</varname></term>
195 <listitem><para>Allow discard requests
196 to be passed through the encrypted
197 block device. This improves
198 performance on SSD storage but has
200 implications.</para></listitem>
204 <term><varname>luks</varname></term>
206 <listitem><para>Force LUKS mode.</para></listitem>
210 <term><varname>plain</varname></term>
212 <listitem><para>Force plain encryption
213 mode.</para></listitem>
217 <term><varname>timeout=</varname></term>
219 <listitem><para>Specify the timeout
220 for querying for a password. If no
221 unit is specified seconds is used.
222 Supported units are s, ms,
223 us, min, h, d. A timeout of 0 waits
224 indefinitely.</para></listitem>
228 <term><varname>noauto</varname></term>
230 <listitem><para> This device will not
231 be automatically unlocked on
232 boot. </para></listitem>
236 <term><varname>nofail</varname></term>
238 <listitem><para>The system will not
239 wait for the device to show up and be
240 unlocked at boot, and not fail the
241 boot if it doesn't show
242 up.</para></listitem>
246 <term><varname>swap</varname></term>
248 <listitem><para> The encrypted block
249 device will be used as a swap
250 partition, and will be formatted as a
251 swap partition after setting up the
252 encrypted block device, with
253 <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
255 <para>WARNING: Using the
256 <varname>swap</varname> option will
257 destroy the contents of the named
258 partition during every boot, so make
259 sure the underlying block device is
261 correctly. </para></listitem>
265 <term><varname>tmp</varname></term>
267 <listitem><para>The encrypted block
268 device will be prepared for using it
269 as <filename>/tmp</filename>
270 partition: it will be formatted using
271 <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
273 <para>WARNING: Using the
274 <varname>tmp</varname> option will
275 destroy the contents of the named
276 partition during every boot, so make
277 sure the underlying block device is
279 correctly. </para></listitem>
283 <para>At early boot and when the system manager
284 configuration is reloaded this file is translated into
286 by <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
290 <title>Example</title>
292 <title>/etc/crypttab example</title>
293 <para>Set up two encrypted block devices with
294 LUKS: one normal one for storage, and another
295 one for usage as swap device.</para>
297 <programlisting>luks-2505567a-9e27-4efe-a4d5-15ad146c258b UUID=2505567a-9e27-4efe-a4d5-15ad146c258b - timeout=0
298 swap /dev/sda7 /dev/urandom swap</programlisting>
303 <title>See Also</title>
305 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
306 <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
307 <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
308 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
309 <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
310 <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>