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>
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 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 not
222 seconds. Supported units are s, ms,
223 us, min, h, d.</para></listitem>
227 <term><varname>noauto</varname></term>
229 <listitem><para> This device will not
230 be automatically unlocked on
231 boot. </para></listitem>
235 <term><varname>nofail</varname></term>
237 <listitem><para>The system will not
238 wait for the device to show up and be
239 unlocked at boot, and not fail the
240 boot if it doesn't show
241 up.</para></listitem>
245 <term><varname>swap</varname></term>
247 <listitem><para> The encrypted block
248 device will be used as a swap
249 partition, and will be formatted as a
250 swap partition after setting up the
251 encrypted block device, with
252 <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
254 <para>WARNING: Using the
255 <varname>swap</varname> option will
256 destroy the contents of the named
257 partition during every boot, so make
258 sure the underlying block device is
260 correctly. </para></listitem>
264 <term><varname>tmp</varname></term>
266 <listitem><para>The encrypted block
267 device will be prepared for using it
268 as <filename>/tmp</filename>
269 partition: it will be formatted using
270 <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
272 <para>WARNING: Using the
273 <varname>tmp</varname> option will
274 destroy the contents of the named
275 partition during every boot, so make
276 sure the underlying block device is
278 correctly. </para></listitem>
282 <para>At early boot and when the system manager
283 configuration is reloaded this file is translated into
285 by <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
289 <title>Example</title>
291 <title>/etc/crypttab example</title>
292 <para>Set up two encrypted block devices with
293 LUKS: one normal one for storage, and another
294 one for usage as swap device.</para>
296 <programlisting>luks-2505567a-9e27-4efe-a4d5-15ad146c258b UUID=2505567a-9e27-4efe-a4d5-15ad146c258b - timeout=0
297 swap /dev/sda7 /dev/urandom swap</programlisting>
302 <title>See Also</title>
304 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
305 <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
306 <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
307 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
308 <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
309 <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>