~siretart/cryptsetup/debian

« back to all changes in this revision

Viewing changes to debian/doc/crypttab.xml

  • Committer: Reinhard Tartler
  • Date: 2008-06-13 19:35:34 UTC
  • Revision ID: siretart@tauware.de-20080613193534-oeqhbxi7r0q4lk51
import cryptsetup_1.0.6-2.dsc

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
<?xml version="1.0" encoding="UTF-8"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
3
 
 
4
<refentry id="file.crypttab">
 
5
 
 
6
 <xi:include href="variables.xml"
 
7
             xpointer="xpointer(/refentry/refentryinfo)"
 
8
             xmlns:xi="http://www.w3.org/2001/XInclude"/>
 
9
 
 
10
 <refmeta>
 
11
  <refentrytitle>crypttab</refentrytitle>
 
12
  <manvolnum>5</manvolnum>
 
13
  <xi:include href="variables.xml"
 
14
              xpointer="xpointer(/refentry/refmeta/*)"
 
15
              xmlns:xi="http://www.w3.org/2001/XInclude"/>
 
16
 </refmeta>
 
17
 
 
18
 <refnamediv>
 
19
  <refname>crypttab</refname>
 
20
  <refpurpose>static information about encrypted filesystems</refpurpose>
 
21
 </refnamediv>
 
22
 
 
23
 <refsect1 id="crypttab.description">
 
24
  <title>DESCRIPTION</title>
 
25
  <simpara>
 
26
   The file <filename>/etc/crypttab</filename> contains descriptive
 
27
   information about encrypted filesystems. <filename>crypttab</filename>
 
28
   is only read by programs, and not written; it is the duty of the system
 
29
   administrator to properly create and maintain this file. Each filesystem is
 
30
   described on a separate line; fields on each line are separated by tabs or
 
31
   spaces. Lines starting with <quote>#</quote> are comments, empty lines are 
 
32
   ignored. The order of records in <filename>crypttab</filename> is important
 
33
   because the init scripts sequentially iterate through 
 
34
   <filename>crypttab</filename> doing their thing.
 
35
  </simpara>
 
36
  <simpara>
 
37
   The first field, <emphasis>target</emphasis>, describes the mapped
 
38
   device name. It must be a plain filename without any directory components.
 
39
   A mapped device which encrypts/decrypts data to/from the <emphasis>source
 
40
   device</emphasis> will be created at
 
41
   <filename class="devicefile">/dev/mapper/target</filename> by
 
42
   <command moreinfo="refentry">cryptsetup</command>.
 
43
  </simpara>
 
44
  <simpara>
 
45
   The second field, <emphasis>source device</emphasis>, describes either the
 
46
   block special device or file (which will be automatically mounted as a loop
 
47
   device) that should hold the encrypted data.
 
48
  </simpara>
 
49
  <simpara>
 
50
   The third field, <emphasis>key file</emphasis>, describes the file to use
 
51
   as a key for decrypting the data of the <emphasis>source device</emphasis>.
 
52
   It can also be a device name (e.g.
 
53
   <filename class="devicefile">/dev/random</filename>), note however that
 
54
   LUKS requires a persistent key and therefore does <emphasis>not</emphasis>
 
55
   support random data keys.
 
56
  </simpara>
 
57
  <simpara>
 
58
   If the <emphasis>key file</emphasis> is the string <quote>none</quote>, 
 
59
   a passphrase will be read interactively from the console. In this case, the
 
60
   options precheck, check, checkargs and tries may be useful.
 
61
  </simpara>
 
62
  <simpara>
 
63
   The fourth field, <emphasis>options</emphasis>, describes the cryptsetup
 
64
   options associated with the encryption process. At minimum, the field should
 
65
   contain the string <emphasis>luks</emphasis> or the
 
66
   <emphasis>cipher</emphasis>, <emphasis>hash</emphasis> and
 
67
   <emphasis>size</emphasis> options.
 
68
  </simpara>
 
69
  <simpara>
 
70
   Options are in the format: <emphasis>key</emphasis>=<emphasis>value</emphasis>
 
71
   [,<emphasis>key</emphasis>=<emphasis>value</emphasis> &#8230;]. The
 
72
   supported options are described below.
 
73
  </simpara>
 
74
  <simpara>
 
75
   Note that all four fields are mandatory and that a missing field will lead
 
76
   to unspecified behaviour.
 
77
  </simpara>
 
78
 </refsect1>
 
79
 
 
80
 <refsect1 id="crypttab.options">
 
81
  <title>OPTIONS</title>
 
82
  <variablelist>
 
83
   <varlistentry>
 
84
    <term><emphasis>cipher</emphasis>=&lt;cipher&gt;</term>
 
85
    <listitem>
 
86
     <simpara>
 
87
      Encryption algorithm. See <command>cryptsetup -c</command>.
 
88
     </simpara>
 
89
    </listitem>
 
90
   </varlistentry>
 
91
 
 
92
   <varlistentry>
 
93
    <term><emphasis>size</emphasis>=&lt;size&gt;</term>
 
94
    <listitem>
 
95
     <simpara>
 
96
      Encryption key size. See <command>cryptsetup -s</command>.
 
97
     </simpara>
 
98
    </listitem>
 
99
   </varlistentry>
 
100
 
 
101
   <varlistentry>
 
102
    <term><emphasis>hash</emphasis>=&lt;hash&gt;</term>
 
103
    <listitem>
 
104
     <simpara>
 
105
      Hash algorithm. See <command>cryptsetup -h</command>.
 
106
     </simpara>
 
107
    </listitem>
 
108
   </varlistentry>
 
109
 
 
110
   <varlistentry>
 
111
    <term><emphasis>offset</emphasis>=&lt;offset&gt;</term>
 
112
    <listitem>
 
113
     <simpara>
 
114
      Start offset. Uses <emphasis role="strong">cryptsetup -o</emphasis>.
 
115
     </simpara>
 
116
    </listitem>
 
117
   </varlistentry>
 
118
 
 
119
   <varlistentry>
 
120
    <term><emphasis>skip</emphasis>=&lt;skip&gt;</term>
 
121
    <listitem>
 
122
     <simpara>
 
123
      Skip sectors at the beginning. Uses <emphasis role="strong">cryptsetup -p</emphasis>.
 
124
     </simpara>
 
125
    </listitem>
 
126
   </varlistentry>
 
127
 
 
128
   <varlistentry>
 
129
    <term><emphasis>verify</emphasis></term>
 
130
    <listitem>
 
131
     <simpara>
 
132
      Verify password. Uses <emphasis role="strong">cryptsetup -y</emphasis>.
 
133
     </simpara>
 
134
    </listitem>
 
135
   </varlistentry>
 
136
 
 
137
   <varlistentry>
 
138
    <term><emphasis>readonly</emphasis></term>
 
139
    <listitem>
 
140
     <simpara>The backing device is read-only (eg: a dvd).</simpara>
 
141
    </listitem>
 
142
   </varlistentry>
 
143
 
 
144
   <varlistentry>
 
145
    <term><emphasis>luks</emphasis></term>
 
146
    <listitem>
 
147
     <simpara>Use device with luks extensions.</simpara>
 
148
    </listitem>
 
149
   </varlistentry>
 
150
 
 
151
   <varlistentry>
 
152
    <term><emphasis>swap</emphasis></term>
 
153
    <listitem>
 
154
     <simpara>
 
155
      Run <command moreinfo="refentry">mkswap</command> on the created device.
 
156
     </simpara>
 
157
    </listitem>
 
158
   </varlistentry>
 
159
 
 
160
   <varlistentry>
 
161
    <term><emphasis>tmp</emphasis>=&lt;tmpfs&gt;</term>
 
162
    <listitem>
 
163
     <simpara>
 
164
      Run <command moreinfo="refentry">mkfs</command> with filesystem type
 
165
      &lt;tmpfs&gt; on the created device. Default is ext2.
 
166
     </simpara>
 
167
    </listitem>
 
168
   </varlistentry>
 
169
 
 
170
   <varlistentry>
 
171
    <term><emphasis>precheck</emphasis>=&lt;precheck&gt;</term>
 
172
    <listitem>
 
173
     <simpara>Check the source device by suitable program; if the check fails,
 
174
      the device is not created; &lt;precheck&gt; is a script to check the
 
175
      source device. The sourcedevice is given as an argument to the script.
 
176
     </simpara>
 
177
    </listitem>
 
178
   </varlistentry>
 
179
 
 
180
   <varlistentry>
 
181
    <term><emphasis>check</emphasis>=&lt;check&gt;</term>
 
182
    <listitem>
 
183
     <simpara>Check the content of the device by a suitable program; if the
 
184
      check fails, the device is removed. If a program is provided as an
 
185
      argument, it is run, giving the decrypted volume (target device) as the
 
186
      first argument, and the value of the checkargs option as the second
 
187
      argument. Cryptdisks searches for the given program in
 
188
      <filename class="directory">/lib/cryptsetup/checks/</filename>.
 
189
      Default is <filename>vol_id</filename>.
 
190
     </simpara>
 
191
    </listitem>
 
192
   </varlistentry>
 
193
 
 
194
   <varlistentry>
 
195
    <term><emphasis>checkargs</emphasis>=&lt;arguments&gt;</term>
 
196
    <listitem>
 
197
     <simpara>Give &lt;arguments&gt; as the second argument to the check
 
198
      script. See the CHECKSCRIPTS section for more information.
 
199
     </simpara>
 
200
    </listitem>
 
201
   </varlistentry>
 
202
 
 
203
   <varlistentry>
 
204
    <term><emphasis>tries</emphasis>=&lt;num&gt;</term>
 
205
    <listitem>
 
206
     <simpara>The input of the passphrase is tried &lt;num&gt; times in case
 
207
      of failure. If you want to disable retries, pass <quote>tries=1</quote>.
 
208
      Default is 3. For the root device, <quote>tries=0</quote> enables
 
209
      infinitive retries due to a special case in the initramfs scripts.
 
210
     </simpara>
 
211
    </listitem>
 
212
   </varlistentry>
 
213
 
 
214
   <varlistentry>
 
215
    <term><emphasis>timeout</emphasis>=&lt;sec&gt;</term>
 
216
    <listitem>
 
217
     <simpara>
 
218
      If key is <quote>none</quote>, the cryptdisks script interactively
 
219
      prompts for a password. The timeout option specifies the time in
 
220
      seconds to wait for the password before timing out.
 
221
     </simpara>
 
222
    </listitem>
 
223
   </varlistentry>
 
224
 
 
225
   <varlistentry>
 
226
    <term><emphasis>noearly</emphasis></term>
 
227
    <listitem>
 
228
     <simpara>The cryptsetup init scripts are invoked twice during the boot 
 
229
      process - once before lvm, evms, raid, etc. are started and once again
 
230
      after that. Sometimes you need to start your encrypted disks in a special
 
231
      order. With this option the device is ignored during the first invokation
 
232
      of the cryptsetup init scripts.
 
233
     </simpara>
 
234
    </listitem>
 
235
   </varlistentry>
 
236
 
 
237
   <varlistentry>
 
238
    <term><emphasis>noauto</emphasis></term>
 
239
    <listitem>
 
240
     <simpara>Entirely ignore the device at the boot process. It's still
 
241
      possible to map the device manually using cryptdisks_start.
 
242
     </simpara>
 
243
    </listitem>
 
244
   </varlistentry>
 
245
 
 
246
   <varlistentry>
 
247
    <term><emphasis>loud</emphasis></term>
 
248
    <listitem>
 
249
     <simpara>Be loud. Print warnings if a device does not exist.</simpara>
 
250
    </listitem>
 
251
   </varlistentry>
 
252
 
 
253
   <varlistentry>
 
254
    <term><emphasis>keyscript</emphasis>=&lt;path&gt;</term>
 
255
    <listitem>
 
256
     <simpara>
 
257
      The executable at the indicated path is executed with the
 
258
      <emphasis>key file</emphasis> from the thirdfield of the crypttab as its
 
259
      only argument and the output is used as the key. This also works with
 
260
      encrypted root filesystems via initramfs if the executable is
 
261
      self-contained (i.e. not a shell script which relies on external
 
262
      programs not present in the standard initramfs environment).
 
263
     </simpara>
 
264
    </listitem>
 
265
   </varlistentry>
 
266
  </variablelist>
 
267
 </refsect1>
 
268
 
 
269
 <refsect1 id="crypttab.checkscripts">
 
270
  <title>CHECKSCRIPTS</title>
 
271
  <variablelist>
 
272
   <varlistentry>
 
273
    <term><emphasis>vol_id</emphasis></term>
 
274
    <listitem>
 
275
     <simpara>Checks for any known filesystem. Supports a filesystem type as
 
276
      argument via&lt;checkargs&gt;:no checkargs - succeeds if any valid
 
277
      filesystem is found on the device."none" - succeeds if no valid
 
278
      filesystem is found on the device."ext3" [or any other filesystem type
 
279
      like xfs, swap, crypto_LUKS, whatever] - succeedsif an ext3 [or another
 
280
      given] filesystem type is found on the device.
 
281
     </simpara>
 
282
    </listitem>
 
283
   </varlistentry>
 
284
 
 
285
   <varlistentry>
 
286
    <term><emphasis>un_vol_id</emphasis></term>
 
287
    <listitem>
 
288
     <simpara>Checks for no known filesystem. Supports a filesystem type as
 
289
      argument via&lt;checkargs&gt;:no checkargs - succeeds if no valid
 
290
      filesystem is found on the device."ext3" [or any other filesystem type
 
291
      like xfs, swap, crypto_LUKS, whatever] - succeedsif no ext3 [or another
 
292
      given] filesystem type is found on the device.
 
293
     </simpara>
 
294
    </listitem>
 
295
   </varlistentry>
 
296
 
 
297
   <varlistentry>
 
298
    <term><emphasis>ext2</emphasis></term>
 
299
    <listitem>
 
300
     <simpara>Checks for a valid ext2/ext3 filesystem.</simpara>
 
301
    </listitem>
 
302
   </varlistentry>
 
303
 
 
304
   <varlistentry>
 
305
    <term><emphasis>xfs</emphasis></term>
 
306
    <listitem>
 
307
     <simpara>Checks for a valid xfs filesystem.</simpara>
 
308
    </listitem>
 
309
   </varlistentry>
 
310
  </variablelist>
 
311
 </refsect1>
 
312
 
 
313
 <refsect1 id="crypttab.examples">
 
314
  <title>EXAMPLES</title>
 
315
  <para>
 
316
   <screen>
 
317
# Encrypted swap device
 
318
cswap /dev/sda6 /dev/random swap
 
319
    
 
320
# Encrypted luks disk with interactive password
 
321
cdisk0 /dev/hda1 none luks
 
322
    
 
323
# Encrypted ext2 disk with interactive password
 
324
# - retry 5 times if the check fails
 
325
cdisk1 /dev/sda2 none checkargs=ext2,tries=5
 
326
 
 
327
# Encrypted disk with interactive password
 
328
# - use a nondefault check script
 
329
# - no retries
 
330
cdisk2 /dev/hdc1 none check=customscript,tries=1
 
331
 
 
332
# Encrypted disk with interactive password
 
333
# - twofish as the cipher
 
334
cdisk3 /dev/sda3 none cipher=twofish
 
335
   </screen>
 
336
  </para>
 
337
 </refsect1>
 
338
 
 
339
 <refsect1 id="crypttab.environment">
 
340
  <title>ENVIRONMENT</title>
 
341
  <variablelist>
 
342
   <varlistentry>
 
343
    <term><emphasis>CRYPTDISKS_ENABLE</emphasis></term>
 
344
    <listitem>
 
345
     <simpara>
 
346
      Set to <emphasis>yes</emphasis> to run cryptdisks at startup. Set to
 
347
      <emphasis>no</emphasis> to disable cryptdisks.
 
348
     </simpara>
 
349
    </listitem>
 
350
   </varlistentry>
 
351
 
 
352
   <varlistentry>
 
353
    <term><emphasis>CRYPTDISKS_MOUNT</emphasis></term>
 
354
    <listitem>
 
355
     <simpara>Specifies the mountpoints that are mounted before cryptdisks is
 
356
      invoked. Useful for keys on removable devices, such as cdrom, usbstick,
 
357
      flashcard, etc.
 
358
     </simpara>
 
359
    </listitem>
 
360
   </varlistentry>
 
361
 
 
362
   <varlistentry>
 
363
    <term><emphasis>CRYPTDISKS_CHECK</emphasis></term>
 
364
    <listitem>
 
365
     <simpara>Specifies the checkscript to be run against the target device,
 
366
      after cryptdisks has been invoked. The target device is passed as the
 
367
      first and only argument to the checkscript. Takes effect if the
 
368
      <emphasis>check</emphasis> option is given in crypttab with no value.
 
369
     </simpara>
 
370
    </listitem>
 
371
   </varlistentry>
 
372
 
 
373
   <varlistentry>
 
374
    <term><emphasis>CRYPTDISKS_PRECHECK</emphasis></term>
 
375
    <listitem>
 
376
     <simpara>Specifies the checkscript to be run against the source device,
 
377
      before cryptdisks has been invoked. The source device is given as the
 
378
      first and only argument to the checkscript. Takes effect if the
 
379
      <emphasis>precheck</emphasis> option is given in crypttab with no value.
 
380
     </simpara>
 
381
    </listitem>
 
382
   </varlistentry>
 
383
 
 
384
   <varlistentry>
 
385
    <term><emphasis>CRYPTDISKS_TIMEOUT</emphasis></term>
 
386
    <listitem>
 
387
     <simpara>Specifies the time in seconds to wait for the password before
 
388
      timing out. Takes effect if the <emphasis>timeout</emphasis> option is
 
389
      given in crypttab with no value.
 
390
     </simpara>
 
391
    </listitem>
 
392
   </varlistentry>
 
393
  </variablelist>
 
394
 </refsect1>
 
395
 
 
396
 <refsect1 id="crypttab.see_also">
 
397
  <title>SEE ALSO</title>
 
398
  <simplelist type="inline">
 
399
   <member><command moreinfo="refentry">cryptsetup</command>(8)</member>
 
400
   <member><filename>/etc/crypttab</filename></member>
 
401
  </simplelist>
 
402
 </refsect1>
 
403
 
 
404
 <refsect1 id="crypttab.author">
 
405
  <title>AUTHOR</title>
 
406
  <simpara>
 
407
   This manual page was originally written by
 
408
   <author>
 
409
    <firstname>Bastian</firstname>
 
410
    <surname>Kleineidam</surname>
 
411
   </author>
 
412
   <email>calvin@debian.org</email>
 
413
   for the Debian distribution of cryptsetup. It has been further improved by
 
414
   <author>
 
415
    <firstname>Michael</firstname>
 
416
    <surname>Gebetsroither</surname>
 
417
   </author>
 
418
   <email>michael.geb@gmx.at</email>,
 
419
   <author>
 
420
    <firstname>Jonas</firstname>
 
421
    <surname>Meurer</surname>
 
422
   </author>
 
423
   <email>jonas@freesources.org</email>
 
424
   and
 
425
   <author>
 
426
    <firstname>David</firstname>
 
427
    <surname>Härdeman</surname>
 
428
   </author>
 
429
   <email>david@hardeman.nu</email>.
 
430
  </simpara>
 
431
 </refsect1>
 
432
 
 
433
</refentry>