Debian Codegraph @

upstream/debian-unstable/man5/crypttab.5

raw
1 '\" t
2 .\" Title: crypttab
3 .\" Author: [see the "AUTHOR" section]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 2026-05-03
6 .\" Manual: cryptsetup manual
7 .\" Source: cryptsetup 2:2.8.6-2
8 .\" Language: English
9 .\"
10 .TH "CRYPTTAB" "5" "2026\-05\-03" "cryptsetup 2:2\&.8\&.6\-2" "cryptsetup manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 crypttab \- static information about encrypted filesystems
32 .SH "DESCRIPTION"
33 .sp
34 The file /etc/crypttab contains descriptive information about encrypted devices\&. crypttab is only read by programs (e\&.g\&. \fBcryptdisks_start\fR and \fBcryptdisks_stop\fR), and not written; it is the duty of the system administrator to properly create and maintain this file\&. crypttab entries are treated sequentially, so their order matters (dependencies need to listed first)\&.
35 .sp
36 Each encrypted device is described on a separate line\&. Fields on each line are separated by tabs or spaces\&. Lines starting with \*(Aq#\*(Aq are comments, and blank lines are ignored\&. Octal sequences \e0\fInum\fR within a field are decoded, which can be used for values containing spaces or special characters\&. A backslash which doesn\*(Aqt start an octal sequence yields undefined behavior\&.
37 .sp
38 The first field, \fItarget\fR, describes the mapped device name\&. It must be a plain filename without any directory components\&. A mapped device which encrypts/decrypts data to/from the \fIsource device\fR will be created at /dev/mapper/target by \fBcryptsetup\fR\&.
39 .sp
40 The second field, \fIsource device\fR, describes either the block special device or file that contains the encrypted data\&. Instead of giving the \fIsource device\fR explicitly, the UUID (resp\&. LABEL, PARTUUID and PARTLABEL) is supported as well, using \(lqUUID=<uuid>\(rq (resp\&. \(lqLABEL=<label>\(rq, \(lqPARTUUID=<partuuid>\(rq and \(lqPARTLABEL=<partlabel>\(rq)\&.
41 .sp
42 The third field, \fIkey file\fR, describes the file to use as a key for decrypting the data of the \fIsource device\fR\&. In case of a \fIkeyscript\fR, the value of this field is given as argument to the keyscript\&. Note that the \fIentire\fR key file will be used as the passphrase; the passphrase must \fInot\fR be followed by a newline character\&.
43 .sp
44 It can also be a device name (e\&.g\&. /dev/urandom), note however that LUKS requires a persistent key and therefore does \fInot\fR support random data keys\&.
45 .sp
46 If the \fIkey file\fR is the string \fInone\fR, a passphrase will be read interactively from the console\&. In this case, the options check, checkargs and tries may be useful\&.
47 .sp
48 The fourth field, \fIoptions\fR, is an optional comma\-separated list of options and/or flags describing the device type (\fIluks\fR, \fItcrypt\fR, \fIbitlk\fR, \fIfvault2\fR, or \fIplain\fR which is also the default) and cryptsetup options associated with the encryption process\&. The supported options are described below\&. For plain dm\-crypt devices the \fIcipher\fR, \fIhash\fR and \fIsize\fR options are required\&. Some options can be changed on active mappings using \fBcryptsetup refresh [<options>] <name>\fR\&. Furthermore some options can be permanently written into metadata of LUKS2 headers using cryptsetup\*(Aqs \fI\-\-persistent\fR flag\&.
49 .sp
50 Note that the first three fields are required and that a missing field will lead to unspecified behaviour\&.
51 .SH "ON DIFFERENT CRYPTTAB FORMATS"
52 .sp
53 Please note that there are several independent cryptsetup wrappers with their own \fIcrypttab\fR format\&. This manpage covers Debian\*(Aqs implementation for \fIinitramfs\fR scripts and \fISysVinit\fR init scripts\&. \fIsystemd\fR brings its own \fIcrypttab\fR implementation\&. We try to cover the differences between the \fIsystemd\fR and our implementation in this manpage, but if in doubt, better check the \fIsystemd\fR \fBcrypttab\fR(5) manpage, e\&.g\&. online at \m[blue]\fB\%https://www.freedesktop.org/software/systemd/man/crypttab.html\fR\m[]\&.
54 .SH "OPTIONS"
55 .PP
56 \fIcipher\fR=<cipher>
57 .RS 4
58 Encryption algorithm (ignored for LUKS and TCRYPT devices)\&. See
59 \fBcryptsetup \-c\fR\&.
60 .RE
61 .PP
62 \fIsize\fR=<size>
63 .RS 4
64 Encryption key size (ignored for LUKS and TCRYPT devices)\&. See
65 \fBcryptsetup \-s\fR\&.
66 .RE
67 .PP
68 \fIsector\-size\fR=<bytes>
69 .RS 4
70 Sector size\&. See
71 \fBcryptsetup\fR(8)
72 for possible values and the default value of this option\&.
73 .RE
74 .PP
75 \fIhash\fR=<hash>
76 .RS 4
77 Hash algorithm (ignored for LUKS and TCRYPT devices)\&. See
78 \fBcryptsetup \-h\fR\&.
79 .RE
80 .PP
81 \fIoffset\fR=<offset>
82 .RS 4
83 Start offset (ignored for LUKS and TCRYPT devices)\&. Uses
84 \fBcryptsetup \-o\fR\&.
85 .RE
86 .PP
87 \fIskip\fR=<skip>
88 .RS 4
89 Skip sectors at the beginning (ignored for LUKS and TCRYPT devices)\&. Uses
90 \fBcryptsetup \-p\fR\&.
91 .RE
92 .PP
93 \fIkeyfile\-offset\fR=<keyfile\-offset>
94 .RS 4
95 Specifies the number of bytes to skip at the start of the key file\&.
96 .RE
97 .PP
98 \fIkeyfile\-size\fR=<keyfile\-size>
99 .RS 4
100 Specifies the maximum number of bytes to read from the key file\&. The default is to read the whole file up to the compiled\-in maximum, that can be queried with
101 \fBcryptsetup \-\-help\fR\&. This option is ignored for plain dm\-crypt devices, as the key file size is then given by the encryption key size (option
102 \fIsize\fR)\&.
103 .RE
104 .PP
105 \fIkeyslot\fR=<slot>, \fIkey\-slot\fR=<slot>
106 .RS 4
107 Key slot (ignored for non\-LUKS devices)\&. See
108 \fBcryptsetup \-S\fR\&.
109 .RE
110 .PP
111 \fIheader\fR=<path>
112 .RS 4
113 Detached header file (ignored for plain dm\-crypt devices)\&. See
114 \fBcryptsetup \-\-header\fR\&.
115 .RE
116 .PP
117 \fIverify\fR
118 .RS 4
119 Verify password\&. Uses
120 \fBcryptsetup \-y\fR\&.
121 .RE
122 .PP
123 \fIreadonly\fR, \fIread\-only\fR
124 .RS 4
125 Set up a read\-only mapping\&.
126 .RE
127 .PP
128 \fItries\fR=<num>
129 .RS 4
130 Try to unlock the device <num> before failing\&. It\*(Aqs particularly useful when using a passphrase or a
131 \fIkeyscript\fR
132 that asks for interactive input\&. If you want to disable retries, pass
133 \(lqtries=1\(rq\&. Default is
134 \(lq3\(rq\&. Setting
135 \(lqtries=0\(rq
136 means infinitive retries\&.
137 .RE
138 .PP
139 \fIdiscard\fR
140 .RS 4
141 Allow using of discards (TRIM) requests for device\&.
142 .sp
143 Starting with Debian 10 (Buster), this option is added per default to new dm\-crypt devices by the Debian Installer\&. If you don\*(Aqt care about leaking access patterns (filesystem type, used space) and don\*(Aqt have hidden truecrypt volumes inside this volume, then it should be safe to enable this option\&. See the following warning for further information\&.
144 .sp
145 \fBWARNING\fR: Assess the specific security risks carefully before enabling this option\&. For example, allowing discards on encrypted devices may lead to the leak of information about the ciphertext device (filesystem type, used space etc\&.) if the discarded blocks can be located easily on the device later\&.
146 .RE
147 .PP
148 \fIluks\fR
149 .RS 4
150 Force LUKS mode\&. When this mode is used, the following options are ignored since they are provided by the LUKS header on the device:
151 \fIcipher=\fR,
152 \fIhash=\fR,
153 \fIsize=\fR
154 .RE
155 .PP
156 \fIplain\fR
157 .RS 4
158 Force plain encryption mode\&.
159 .RE
160 .PP
161 \fIbitlk\fR
162 .RS 4
163 Force BITLK (Windows BitLocker\-compatible) mode\&. WARNING:
164 \fIcrypttab\fR
165 support is currently experimental\&.
166 .RE
167 .PP
168 \fIfvault2\fR
169 .RS 4
170 Force Apple\*(Aqs FileVault2 mode\&. Only the (legacy) FileVault2 format based on Core Storage and HFS+ filesystem (introduced in MacOS X 10\&.7 Lion) is currently supported; the new version of FileVault based on the APFS filesystem used in recent macOS versions is not supported\&.
171 .RE
172 .PP
173 \fItcrypt\fR
174 .RS 4
175 Use TrueCrypt encryption mode\&. When this mode is used, the following options are ignored since they are provided by the TrueCrypt header on the device or do not apply:
176 \fIcipher=\fR,
177 \fIhash=\fR,
178 \fIkeyfile\-offset=\fR,
179 \fIkeyfile\-size=\fR,
180 \fIsize=\fR
181 .RE
182 .PP
183 \fIveracrypt\fR, \fItcrypt\-veracrypt\fR
184 .RS 4
185 Use VeraCrypt extension to TrueCrypt device\&. Only useful in conjunction with
186 \fItcrypt\fR
187 option (ignored for non\-TrueCrypt devices)\&.
188 .RE
189 .PP
190 \fItcrypthidden\fR, \fItcrypt\-hidden\fR
191 .RS 4
192 Use hidden TCRYPT header (ignored for non\-TCRYPT devices)\&.
193 .RE
194 .PP
195 \fIsame\-cpu\-crypt\fR
196 .RS 4
197 Perform encryption using the same cpu that IO was submitted on\&.
198 .RE
199 .PP
200 \fIsubmit\-from\-crypt\-cpus\fR
201 .RS 4
202 Disable offloading writes to a separate thread after encryption\&.
203 .RE
204 .PP
205 \fIno\-read\-workqueue\fR, \fIno\-write\-workqueue\fR
206 .RS 4
207 Bypass dm\-crypt internal workqueue and process read or write requests synchronously\&.
208 .RE
209 .PP
210 \fIswap\fR
211 .RS 4
212 Run
213 \fBmkswap\fR
214 on the created device\&.
215 .sp
216 This option is ignored for
217 \fIinitramfs\fR
218 devices\&.
219 .RE
220 .PP
221 \fItmp\fR[=<tmpfs>]
222 .RS 4
223 Run
224 \fBmkfs\fR
225 with filesystem type <tmpfs> (or ext4 if omitted) on the created device\&.
226 .sp
227 This option is ignored for
228 \fIinitramfs\fR
229 devices\&.
230 .RE
231 .PP
232 \fIcheck\fR[=<check>]
233 .RS 4
234 Check the content of the target device by a suitable program; if the check fails, the device is closed immediately\&. The program is being run with decrypted volume (target device) as first positional argument and, if the
235 \fIcheckargs\fR
236 option is used, its value as second argument\&. See the CHECKSCRIPTS section for more information\&.
237 .sp
238 The program is either specified by full path or relative to
239 /lib/cryptsetup/checks/\&. If omitted, then the value of $CRYPTDISKS_CHECK set in
240 /etc/default/cryptdisks
241 is used (blkid
242 by default)\&.
243 .sp
244 This option is specific to the Debian
245 \fIcrypttab\fR
246 format\&. It\*(Aqs not supported by
247 \fIsystemd\fR\&.
248 .RE
249 .PP
250 \fIcheckargs\fR=<arguments>
251 .RS 4
252 Give <arguments> as the second argument to the check script\&. See the CHECKSCRIPTS section for more information\&.
253 .sp
254 This option is specific to the Debian \fIcrypttab\fR format\&. It\*(Aqs not supported by \fIsystemd\fR\&.
255 .RE
256 .PP
257 \fIinitramfs\fR
258 .RS 4
259 The initramfs hook processes the root device, any resume devices and any devices with the
260 \fIinitramfs\fR
261 option set\&. These devices are processed within the initramfs stage of boot\&. As an example, that allows the use of remote unlocking using dropbear\&.
262 .sp
263 This option is specific to the Debian
264 \fIcrypttab\fR
265 format\&. It\*(Aqs not supported by
266 \fIsystemd\fR\&.
267 .RE
268 .PP
269 \fInoearly\fR
270 .RS 4
271 The cryptsetup init scripts are invoked twice during the boot process \- once before lvm, raid, etc\&. are started and once again after that\&. Sometimes you need to start your encrypted disks in a special order\&. With this option the device is ignored during the first invocation of the cryptsetup init scripts\&.
272 .sp
273 This option is ignored for
274 \fIinitramfs\fR
275 devices and specific to the Debian
276 \fIcrypttab\fR
277 format\&. It\*(Aqs not supported by
278 \fIsystemd\fR\&.
279 .RE
280 .PP
281 \fInoauto\fR
282 .RS 4
283 Entirely ignore the device at the boot process\&. It\*(Aqs still possible to map the device manually using cryptdisks_start\&.
284 .sp
285 This option is ignored for
286 \fIinitramfs\fR
287 devices and specific to the Debian
288 \fIcrypttab\fR
289 format\&.
290 .RE
291 .PP
292 \fIloud\fR
293 .RS 4
294 Be loud\&. Print warnings if a device does not exist\&. This option overrides the option
295 \fIquiet\fR\&.
296 .sp
297 This option is ignored for
298 \fIinitramfs\fR
299 devices and specific to the Debian
300 \fIcrypttab\fR
301 format\&. It\*(Aqs not supported by
302 \fIsystemd\fR\&.
303 .RE
304 .PP
305 \fIquiet\fR
306 .RS 4
307 Be quiet\&. Don\*(Aqt print warnings if a device does not exist\&. This option overrides the option
308 \fIloud\fR\&.
309 .sp
310 This option is ignored for
311 \fIinitramfs\fR
312 devices and specific to the Debian
313 \fIcrypttab\fR
314 format\&. It\*(Aqs not supported by
315 \fIsystemd\fR\&.
316 .RE
317 .PP
318 \fIkeyscript\fR=<path>
319 .RS 4
320 The executable at the indicated path is executed with the value of the
321 \fIthird field\fR
322 as only argument\&. The keyscript\*(Aqs standard output is passed to cryptsetup as decyption key\&. Its exit status is currently ignored, but no assumption should be made in that regard\&. When used in initramfs, the executable either needs to be self\-contained (i\&.e\&. doesn\*(Aqt rely on any external program which is not present in the initramfs environment) or the dependencies have to added to the initramfs image by other means\&. The program is either specified by full path or relative to
323 /lib/cryptsetup/scripts/\&.
324 .sp
325 LIMITATIONS: All binaries and files on which the keyscript depends must be available at the time of execution\&. Special care needs to be taken for encrypted filesystems like /usr or /var\&. As an example, unlocking encrypted /usr must not depend on binaries from /usr/(s)bin\&.
326 .sp
327 This option is specific to the Debian
328 \fIcrypttab\fR
329 format\&. It\*(Aqs not supported by
330 \fIsystemd\fR\&.
331 .sp
332 WARNING: With systemd as init system, this option might be ignored\&. At the time this is written (December 2016), the systemd cryptsetup helper doesn\*(Aqt support the keyscript option to /etc/crypttab\&. For the time being, the only option to use keyscripts along with systemd is to force processing of the corresponding crypto devices in the initramfs\&. See the \*(Aqinitramfs\*(Aq option for further information\&.
333 .sp
334 All fields of the appropriate crypttab entry are available to the keyscript as exported environment variables:
335 .PP
336 CRYPTTAB_NAME, _CRYPTTAB_NAME
337 .RS 4
338 The target name (after resp\&. before octal sequence decoding)\&.
339 .RE
340 .PP
341 CRYPTTAB_SOURCE, _CRYPTTAB_SOURCE
342 .RS 4
343 The source device (after resp\&. before octal sequence decoding and device resolution)\&.
344 .RE
345 .PP
346 CRYPTTAB_KEY, _CRYPTTAB_KEY
347 .RS 4
348 The value of the third field (after resp\&. before octal sequence decoding)\&.
349 .RE
350 .PP
351 CRYPTTAB_OPTIONS, _CRYPTTAB_OPTIONS
352 .RS 4
353 A list of exported crypttab options (after resp\&. before octal sequence decoding)\&.
354 .RE
355 .PP
356 CRYPTTAB_OPTION_<option>
357 .RS 4
358 The value of the appropriate crypttab option, with value set to \*(Aqyes\*(Aq in case the option is merely a flag\&. For option aliases, such as \*(Aqreadonly\*(Aq and \*(Aqread\-only\*(Aq, the variable name refers to the first alternative listed (thus \*(AqCRYPTTAB_OPTION_readonly\*(Aq in that case)\&. If the crypttab option name contains \*(Aq\-\*(Aq characters, then they are replaced with \*(Aq_\*(Aq in the exported variable name\&. For instance, the value of the \*(AqCRYPTTAB_OPTION_keyfile_offset\*(Aq environment variable is set to the value of the \*(Aqkeyfile\-offset\*(Aq crypttab option\&.
359 .RE
360 .PP
361 CRYPTTAB_TRIED
362 .RS 4
363 Number of previous tries since start of cryptdisks (counts until maximum number of tries is reached)\&.
364 .RE
365 .sp
366 .RE
367 .SH "CHECKSCRIPTS"
368 .PP
369 \fIblkid\fR
370 .RS 4
371 Checks for any known filesystem\&. Supports a filesystem type as argument via <checkargs>:
372 .sp
373 .RS 4
374 .ie n \{\
375 \h'-04'\(bu\h'+03'\c
376 .\}
377 .el \{\
378 .sp -1
379 .IP \(bu 2.3
380 .\}
381 no checkargs \- succeeds if any valid filesystem is found on the device\&.
382 .RE
383 .sp
384 .RS 4
385 .ie n \{\
386 \h'-04'\(bu\h'+03'\c
387 .\}
388 .el \{\
389 .sp -1
390 .IP \(bu 2.3
391 .\}
392 "none" \- succeeds if no valid filesystem is found on the device\&.
393 .RE
394 .sp
395 .RS 4
396 .ie n \{\
397 \h'-04'\(bu\h'+03'\c
398 .\}
399 .el \{\
400 .sp -1
401 .IP \(bu 2.3
402 .\}
403 "ext4" [or another filesystem type like xfs, swap, crypto_LUKS, \&.\&.\&.] \- succeeds if ext4 filesystem is found on the device\&.
404 .RE
405 .RE
406 .PP
407 \fIun_blkid\fR
408 .RS 4
409 Checks for no known filesystem\&. Supports a filesystem type as argument via <checkargs>:
410 .sp
411 .RS 4
412 .ie n \{\
413 \h'-04'\(bu\h'+03'\c
414 .\}
415 .el \{\
416 .sp -1
417 .IP \(bu 2.3
418 .\}
419 no checkargs \- succeeds if no valid filesystem is found on the device\&.
420 .RE
421 .sp
422 .RS 4
423 .ie n \{\
424 \h'-04'\(bu\h'+03'\c
425 .\}
426 .el \{\
427 .sp -1
428 .IP \(bu 2.3
429 .\}
430 "ext4" [or another filesystem type like xfs, swap, crypto_LUKS, \&.\&.\&.] \- succeeds if no ext4 filesystem is found on the device\&.
431 .RE
432 .RE
433 .SH "EXAMPLES"
434 .PP
435 .if n \{\
436 .RS 4
437 .\}
438 .nf
439 # Encrypted swap device
440 cswap /dev/sda6 /dev/urandom plain,cipher=aes\-xts\-plain64,size=256,hash=sha1,swap
441
442 # Encrypted LUKS disk with interactive password, identified by its UUID, discard enabled
443 cdisk0 UUID=12345678\-9abc\-def012345\-6789abcdef01 none luks,discard
444
445 # Encrypted TCRYPT disk with interactive password, discard enabled
446 tdisk0 /dev/sr0 none tcrypt,discard
447
448 # Encrypted ext4 disk with interactive password, discard enabled
449 # \- retry 5 times if the check fails
450 cdisk1 /dev/sda2 none plain,cipher=aes\-xts\-plain64,size=256,hash=sha1,check,checkargs=ext4,tries=5,discard
451
452 # Encrypted disk with interactive password, discard enabled
453 # \- use a nondefault check script
454 # \- no retries
455 cdisk2 /dev/sdc1 none plain,cipher=aes\-xts\-plain64,size=256,hash=sha1,check=customscript,tries=1,discard
456
457 # Encrypted disk with interactive password, discard enabled
458 # \- Twofish as the cipher, RIPEMD\-160 as the hash
459 cdisk3 /dev/sda3 none plain,cipher=twofish,size=256,hash=ripemd160,discard
460
461 .fi
462 .if n \{\
463 .RE
464 .\}
465 .sp
466 .SH "ENVIRONMENT"
467 .PP
468 \fICRYPTDISKS_ENABLE\fR
469 .RS 4
470 Set to
471 \fIyes\fR
472 to run cryptdisks initscripts at startup\&. Set to
473 \fIno\fR
474 to disable cryptdisks initscripts\&. Default is
475 \fIyes\fR\&.
476 .RE
477 .PP
478 \fICRYPTDISKS_MOUNT\fR
479 .RS 4
480 Specifies the mountpoints that are mounted before cryptdisks is invoked\&. Takes mountpoints configured in /etc/fstab as arguments\&. Separate mountpoints by space\&. This is useful for keys on removable devices, such as cdrom, usbstick, flashcard, etc\&. Default is unset\&.
481 .RE
482 .PP
483 \fICRYPTDISKS_CHECK\fR
484 .RS 4
485 Specifies the default checkscript to be run against the target device, after cryptdisks has been invoked\&. The target device is passed as the first and only argument to the checkscript\&. Takes effect if the
486 \fIcheck\fR
487 option is given in crypttab with no value\&. See documentation for
488 \fIcheck\fR
489 option above for more information\&.
490 .RE
491 .SH "KNOWN UPGRADE ISSUES"
492 .sp
493 The upstream defaults for encryption cipher, hash and keysize have changed several times in the past, and they\*(Aqre expected to change again in future, for example if security issues arise\&. On LUKS devices, the used settings are stored in the LUKS header, and thus don\*(Aqt need to be configured in /etc/crypttab\&. For plain dm\-crypt devices, no information about used cipher, hash and keysize are available at all\&. Therefore we strongly suggest to configure the cipher, hash and keysize in /etc/crypttab for plain dm\-crypt devices, even if they match the current default\&.
494 .SH "SEE ALSO"
495 \fBcryptsetup\fR(8), \fBcryptdisks_start\fR(8), \fBcryptdisks_stop\fR(8), /usr/share/doc/cryptsetup\-initramfs/README\&.initramfs\&.gz
496 .SH "AUTHOR"
497 .sp
498 This manual page was originally written by Bastian Kleineidam <calvin@debian\&.org> for the Debian distribution of cryptsetup\&. It has been further improved by Michael Gebetsroither <michael\&.geb@gmx\&.at>, David Härdeman <david@hardeman\&.nu> and Jonas Meurer <jonas@freesources\&.org>\&.