chiark / gitweb /
f3bde71b4f633ba60dc1966bce0ca880e35dc226
[elogind.git] / man / crypttab.xml
1 <?xml version="1.0"?>
2 <!--*-nxml-*-->
3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!--
5   This file is part of systemd.
6
7   Copyright 2012 Lennart Poettering
8
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.
13
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.
18
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/>.
21
22   This is based on crypttab(5) from Fedora's initscripts package, which in
23   turn is based on Debian's version.
24
25   The Red Hat version has been written by Miloslav Trmac <mitr@redhat.com>.
26
27 -->
28 <refentry id="crypttab">
29
30         <refentryinfo>
31                 <title>crypttab</title>
32                 <productname>systemd</productname>
33
34                 <authorgroup>
35                         <author>
36                                 <contrib>Documentation</contrib>
37                                 <firstname>Miloslav</firstname>
38                                 <surname>Trmac</surname>
39                                 <email>mitr@redhat.com</email>
40                         </author>
41                         <author>
42                                 <contrib>Documentation</contrib>
43                                 <firstname>Lennart</firstname>
44                                 <surname>Poettering</surname>
45                                 <email>lennart@poettering.net</email>
46                         </author>
47                 </authorgroup>
48         </refentryinfo>
49
50         <refmeta>
51                 <refentrytitle>crypttab</refentrytitle>
52                 <manvolnum>5</manvolnum>
53         </refmeta>
54
55         <refnamediv>
56                 <refname>crypttab</refname>
57                 <refpurpose>Configuration for encrypted block devices</refpurpose>
58         </refnamediv>
59
60         <refsynopsisdiv>
61                 <para><filename>/etc/crypttab</filename></para>
62         </refsynopsisdiv>
63
64         <refsect1>
65                 <title>Description</title>
66
67                 <para>The <filename>/etc/crypttab</filename> file
68                 describes encrypted block devices that are set up
69                 during system boot.</para>
70
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
76                 optional.</para>
77
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>
81
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>
88
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>
101
102                 <para>The fourth field, if present, is a
103                 comma-delimited list of options.  The following
104                 options are recognized:</para>
105
106                 <variablelist>
107                         <varlistentry>
108                                 <term><varname>cipher=</varname></term>
109
110                                 <listitem><para>Specifies the cipher
111                                 to use; see
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>
118                         </varlistentry>
119
120
121                         <varlistentry>
122                                 <term><varname>size=</varname></term>
123
124                                 <listitem><para>Specifies the key size
125                                 in bits; see
126                                 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
127                                 for possible values and the default
128                                 value of this
129                                 option. </para></listitem>
130                         </varlistentry>
131
132
133                         <varlistentry>
134                                 <term><varname>hash=</varname></term>
135
136                                 <listitem><para>Specifies the hash to
137                                 use for password hashing; see
138                                 <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for possible values and
139                                 the default value of this
140                                 option. </para></listitem>
141                         </varlistentry>
142
143                         <varlistentry>
144                                 <term><varname>tries=</varname></term>
145
146                                 <listitem><para>Specifies the maximum
147                                 number of times the user is queried
148                                 for a password.</para></listitem>
149                         </varlistentry>
150
151                         <varlistentry>
152                                 <term><varname>verify</varname></term>
153
154                                 <listitem><para> If the the encryption
155                                 password is read from console, it has
156                                 to be entered twice (to prevent
157                                 typos). </para></listitem>
158                         </varlistentry>
159
160                         <varlistentry>
161                                 <term><varname>read-only</varname></term>
162
163                                 <listitem><para>Set up the encrypted
164                                 block device in read-only
165                                 mode.</para></listitem>
166                         </varlistentry>
167
168                         <varlistentry>
169                                 <term><varname>allow-discards</varname></term>
170
171                                 <listitem><para>Allow discard requests
172                                 to be passed through the encrypted
173                                 block device. This improves
174                                 performance on SSD storage but has
175                                 security
176                                 implications.</para></listitem>
177                         </varlistentry>
178
179                         <varlistentry>
180                                 <term><varname>luks</varname></term>
181
182                                 <listitem><para>Force LUKS mode.</para></listitem>
183                         </varlistentry>
184
185                         <varlistentry>
186                                 <term><varname>plain</varname></term>
187
188                                 <listitem><para>Force plain encryption
189                                 mode.</para></listitem>
190                         </varlistentry>
191
192                         <varlistentry>
193                                 <term><varname>timeout=</varname></term>
194
195                                 <listitem><para>Specify the timeout
196                                 for querying for a password. If not
197                                 unit is specified in
198                                 seconds. Supported units are s, ms,
199                                 us, min, h, d.</para></listitem>
200                         </varlistentry>
201
202                         <varlistentry>
203                                 <term><varname>noauto</varname></term>
204
205                                 <listitem><para> This device will not
206                                 be automatically unlocked on
207                                 boot. </para></listitem>
208                         </varlistentry>
209
210                         <varlistentry>
211                                 <term><varname>nofail</varname></term>
212
213                                 <listitem><para>The system will not
214                                 wait for the device to show up and be
215                                 unlocked at boot, and not fail the
216                                 boot if it doesn't show
217                                 up.</para></listitem>
218                         </varlistentry>
219
220                         <varlistentry>
221                                 <term><varname>swap</varname></term>
222
223                                 <listitem><para> The encrypted block
224                                 device will be used as a swap
225                                 partition, and will be formatted as a
226                                 swap partition after setting up the
227                                 encrypted block device, with
228                                 <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
229
230                                 <para>WARNING: Using the
231                                 <varname>swap</varname> option will
232                                 destroy the contents of the named
233                                 partition during every boot, so make
234                                 sure the underlying block device is
235                                 specified
236                                 correctly. </para></listitem>
237                         </varlistentry>
238
239                         <varlistentry>
240                                 <term><varname>tmp</varname></term>
241
242                                 <listitem><para>The encrypted block
243                                 device will be prepared for using it
244                                 as <filename>/tmp</filename>
245                                 partition: it will be formatted using
246                                 <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
247
248                                 <para>WARNING: Using the
249                                 <varname>tmp</varname> option will
250                                 destroy the contents of the named
251                                 partition during every boot, so make
252                                 sure the underlying block device is
253                                 specified
254                                 correctly. </para></listitem>
255                         </varlistentry>
256                 </variablelist>
257
258                 <para>At early boot and when the system manager
259                 configuration is reloaded this file is translated into
260                 native systemd units
261                 by <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
262         </refsect1>
263
264         <refsect1>
265                 <title>Example</title>
266                 <example>
267                         <title>/etc/crypttab example</title>
268                         <para>Set up two encrypted block devices with
269                         LUKS: one normal one for storage, and another
270                         one for usage as swap device.</para>
271
272                         <programlisting>luks-2505567a-9e27-4efe-a4d5-15ad146c258b UUID=2505567a-9e27-4efe-a4d5-15ad146c258b - timeout=0
273 swap /dev/sda7 /dev/urandom swap</programlisting>
274                 </example>
275         </refsect1>
276
277         <refsect1>
278                 <title>See Also</title>
279                 <para>
280                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
281                         <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
282                         <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
283                         <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
284                         <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
285                         <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
286                 </para>
287         </refsect1>
288
289 </refentry>