1CRYPTSETUP-OPEN(8) Maintenance Commands CRYPTSETUP-OPEN(8)
2
6 cryptsetup-open, cryptsetup-create, cryptsetup-plainOpen, cryptsetup-
7 luksOpen, cryptsetup-loopaesOpen, cryptsetup-tcryptOpen, cryptsetup-
8 bitlkOpen, cryptsetup-fvault2Open - open an encrypted device and create
9 a mapping with a specified name
10
12 cryptsetup open --type <device_type> [<options>] <device> <name>
13
15 Opens (creates a mapping with) <name> backed by device <device>.
16 Device type can be plain, luks (default), luks1, luks2, loopaes or
18 tcrypt.
19 For backward compatibility there are open command aliases:
21 create (argument-order <name> <device>): open --type plain
23 plainOpen: open --type plain
24 luksOpen: open --type luks
25 loopaesOpen: open --type loopaes
26 tcryptOpen: open --type tcrypt
27 bitlkOpen: open --type bitlk
28 <options> are type specific and are described below for individual
30 device types. For create, the order of the <name> and <device> options
31 is inverted for historical reasons, all other aliases use the standard
32 <device> <name> order.
33 PLAIN
35 open --type plain <device> <name>
36 plainOpen <device> <name> (old syntax)
37 create <name> <device> (OBSOLETE syntax)
38 Opens (creates a mapping with) <name> backed by device <device>.
40 <options> can be [--hash, --cipher, --verify-passphrase, --sector-size,
42 --key-file, --keyfile-size, --keyfile-offset, --key-size, --offset,
43 --skip, --device-size, --size, --readonly, --shared, --allow-discards,
44 --refresh, --timeout, --verify-passphrase, --iv-large-sectors].
45 Example: 'cryptsetup open --type plain /dev/sda10 e1' maps the raw
47 encrypted device /dev/sda10 to the mapped (decrypted) device
48 /dev/mapper/e1, which can then be mounted, fsck-ed or have a filesystem
49 created on it.
50 LUKS
52 open <device> <name>
53 open --type <luks1|luks2> <device> <name> (explicit version request)
54 luksOpen <device> <name> (old syntax)
55 Opens the LUKS device <device> and sets up a mapping <name> after
57 successful verification of the supplied passphrase.
58 First, the passphrase is searched in LUKS2 tokens unprotected by PIN.
60 If such token does not exist (or fails to unlock keyslot) and also the
61 passphrase is not supplied via --key-file, the command prompts for
62 passphrase interactively.
63 If there is valid LUKS2 token but it requires PIN to unlock assigned
65 keyslot, it is not used unless one of following options is added:
66 --token-only, --token-type where type matches desired PIN protected
67 token or --token-id with id matching PIN protected token.
68 <options> can be [--key-file, --keyfile-offset, --keyfile-size,
70 --readonly, --test-passphrase, --allow-discards, --header, --key-slot,
71 --volume-key-file, --token-id, --token-only, --token-type,
72 --disable-external-tokens, --disable-keyring, --disable-locks, --type,
73 --refresh, --serialize-memory-hard-pbkdf, --unbound, --tries,
74 --timeout, --verify-passphrase, --persistent].
75 loopAES
77 open --type loopaes <device> <name> --key-file <keyfile>
78 loopaesOpen <device> <name> --key-file <keyfile> (old syntax)
79 Opens the loop-AES <device> and sets up a mapping <name>.
81 If the key file is encrypted with GnuPG, then you have to use
83 --key-file=- and decrypt it before use, e.g., like this:
84 gpg --decrypt <keyfile> | cryptsetup loopaesOpen --key-file=- <device>
85 <name>
86 WARNING: The loop-AES extension cannot use the direct input of the key
88 file on the real terminal because the keys are separated by end-of-line
89 and only part of the multi-key file would be read.
90 If you need it in script, just use the pipe redirection:
91 echo $keyfile | cryptsetup loopaesOpen --key-file=- <device> <name>
92 Use --keyfile-size to specify the proper key length if needed.
94 Use --offset to specify device offset. Note that the units need to be
96 specified in number of 512 byte sectors.
97 Use --skip to specify the IV offset. If the original device used an
99 offset and but did not use it in IV sector calculations, you have to
100 explicitly use --skip 0 in addition to the offset parameter.
101 Use --hash to override the default hash function for passphrase hashing
103 (otherwise it is detected according to key size).
104 <options> can be [--cipher, --key-file, --keyfile-size,
106 --keyfile-offset, --key-size, --offset, --skip, --hash, --readonly,
107 --allow-discards, --refresh].
108 TrueCrypt and VeraCrypt
110 open --type tcrypt <device> <name>
111 tcryptOpen <device> <name> (old syntax)
112 Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) <device> and sets
114 up a mapping <name>.
115 <options> can be [--key-file, --tcrypt-hidden, --tcrypt-system,
117 --tcrypt-backup, --readonly, --test-passphrase, --allow-discards,
118 --veracrypt (ignored), --disable-veracrypt, --veracrypt-pim,
119 --veracrypt-query-pim, --header, --cipher, --hash, --tries, --timeout,
120 --verify-passphrase].
121 The keyfile parameter allows a combination of file content with the
123 passphrase and can be repeated. Note that using keyfiles is compatible
124 with TCRYPT and is different from LUKS keyfile logic.
125 If --cipher or --hash options are used, only cipher chains or PBKDF2
127 variants with the specified hash algorithms are checked. This could
128 speed up unlocking the device (but also it reveals some information
129 about the container).
130 If you use --header in combination with hidden or system options, the
132 header file must contain specific headers on the same positions as the
133 original encrypted container.
134 WARNING: Option --allow-discards cannot be combined with option
136 --tcrypt-hidden. For normal mapping, it can cause the destruction of
137 hidden volume (hidden volume appears as unused space for outer volume
138 so this space can be discarded).
139 BitLocker
141 open --type bitlk <device> <name>
142 bitlkOpen <device> <name> (old syntax)
143 Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping
145 <name>.
146 <options> can be [--key-file, --keyfile-offset, --keyfile-size,
148 --key-size, --readonly, --test-passphrase, --allow-discards
149 --volume-key-file, --tries, --timeout, --verify-passphrase].
150 FileVault2
152 open --type fvault2 <device> <name>
153 fvault2Open <device> <name> (old syntax)
154 Opens the FVAULT2 (a FileVault2 compatible) <device> and sets up a
156 mapping <name>.
157 <options> can be [--key-file, --keyfile-offset, --keyfile-size,
159 --key-size, --readonly, --test-passphrase, --allow-discards
160 --volume-key-file, --tries, --timeout, --verify-passphrase].
161
163 --type <device-type>
164 Specifies required device type, for more info read BASIC ACTIONS
165 section in cryptsetup(8).
166 --hash, -h <hash-spec>
168 Specifies the passphrase hash. Applies to plain and loopaes device
169 types only.
170 For tcrypt device type, it restricts checked PBKDF2 variants when
172 looking for header.
173 --cipher, -c <cipher-spec>
175 Set the cipher specification string for plain device type.
176 For tcrypt device type it restricts checked cipher chains when
178 looking for header.
179 cryptsetup --help shows the compiled-in defaults.
181 If a hash is part of the cipher specification, then it is used as
183 part of the IV generation. For example, ESSIV needs a hash
184 function, while "plain64" does not and hence none is specified.
185 For XTS mode you can optionally set a key size of 512 bits with the
187 -s option. Key size for XTS mode is twice that for other modes for
188 the same security level.
189 --verify-passphrase, -y
191 When interactively asking for a passphrase, ask for it twice and
192 complain if both inputs do not match. Advised when creating a plain
193 type mapping for the first time. Ignored on input from file or
194 stdin.
195 --key-file, -d name
197 Read the passphrase from file.
198 If the name given is "-", then the passphrase will be read from
200 stdin. In this case, reading will not stop at newline characters.
201 NOTE: With plain device type, the passphrase obtained via
203 --key-file option is passed directly in dm-crypt. Unlike the
204 interactive mode (stdin) where digest (--hash option) of the
205 passphrase is passed in dm-crypt instead.
206 See section NOTES ON PASSPHRASE PROCESSING in cryptsetup(8) for
208 more information.
209 --keyfile-offset value
211 Skip value bytes at the beginning of the key file.
212 --keyfile-size, -l value
214 Read a maximum of value bytes from the key file. The default is to
215 read the whole file up to the compiled-in maximum that can be
216 queried with --help. Supplying more data than the compiled-in
217 maximum aborts the operation.
218 This option is useful to cut trailing newlines, for example. If
220 --keyfile-offset is also given, the size count starts after the
221 offset.
222 --volume-key-file, --master-key-file (OBSOLETE alias)
224 Use a volume key stored in a file. This allows one to open luks and
225 bitlk device types without giving a passphrase.
226 --key-slot, -S <0-N>
228 This option selects a specific key-slot to compare the passphrase
229 against. If the given passphrase would only match a different
230 key-slot, the operation fails.
231 The maximum number of key slots depends on the LUKS version. LUKS1
233 can have up to 8 key slots. LUKS2 can have up to 32 key slots based
234 on key slot area size and key size, but a valid key slot ID can
235 always be between 0 and 31 for LUKS2.
236 --key-size, -s bits
238 Sets key size in bits. The argument has to be a multiple of 8. The
239 possible key-sizes are limited by the cipher and mode used.
240 See /proc/crypto for more information. Note that key-size in
242 /proc/crypto is stated in bytes.
243 This option can be used for plain device type only.
245 --size, -b <number of 512 byte sectors>
247 Set the size of the device in sectors of 512 bytes. Usable only
248 with plain device type.
249 --offset, -o <number of 512 byte sectors>
251 Start offset in the backend device in 512-byte sectors. This option
252 is only relevant with plain or loopaes device types.
253 --skip, -p <number of 512 byte sectors>
255 Start offset used in IV calculation in 512-byte sectors (how many
256 sectors of the encrypted data to skip at the beginning). This
257 option is only relevant with plain or loopaes device types.
258 Hence, if --offset n, and --skip s, sector n (the first sector of
260 the encrypted device) will get a sector number of s for the IV
261 calculation.
262 --device-size size[units]
264 Instead of real device size, use specified value. Usable only with
265 plain device type.
266 If no unit suffix is specified, the size is in bytes.
268 Unit suffix can be S for 512 byte sectors, K/M/G/T (or
270 KiB,MiB,GiB,TiB) for units with 1024 base or KB/MB/GB/TB for 1000
271 base (SI scale).
272 --readonly, -r
274 set up a read-only mapping.
275 --shared
277 Creates an additional mapping for one common ciphertext device.
278 Arbitrary mappings are supported. This option is only relevant for
279 the plain device type. Use --offset, --size and --skip to specify
280 the mapped area.
281 --timeout, -t <number of seconds>
283 The number of seconds to wait before timeout on passphrase input
284 via terminal. It is relevant every time a passphrase is asked. It
285 has no effect if used in conjunction with --key-file.
286 This option is useful when the system should not stall if the user
288 does not input a passphrase, e.g. during boot. The default is a
289 value of 0 seconds, which means to wait forever.
290 --tries, -T
292 How often the input of the passphrase shall be retried. The default
293 is 3 tries.
294 --allow-discards
296 Allow the use of discard (TRIM) requests for the device. This is
297 also not supported for LUKS2 devices with data integrity
298 protection.
299 WARNING: This command can have a negative security impact because
301 it can make filesystem-level operations visible on the physical
302 device. For example, information leaking filesystem type, used
303 space, etc. may be extractable from the physical device if the
304 discarded blocks can be located later. If in doubt, do not use it.
305 A kernel version of 3.1 or later is needed. For earlier kernels,
307 this option is ignored.
308 --perf-same_cpu_crypt
310 Perform encryption using the same cpu that IO was submitted on. The
311 default is to use an unbound workqueue so that encryption work is
312 automatically balanced between available CPUs.
313 NOTE: This option is available only for low-level dm-crypt
315 performance tuning, use only if you need a change to default
316 dm-crypt behaviour. Needs kernel 4.0 or later.
317 --perf-submit_from_crypt_cpus
319 Disable offloading writes to a separate thread after encryption.
320 There are some situations where offloading write bios from the
321 encryption threads to a single thread degrades performance
322 significantly. The default is to offload write bios to the same
323 thread.
324 NOTE: This option is available only for low-level dm-crypt
326 performance tuning, use only if you need a change to default
327 dm-crypt behaviour. Needs kernel 4.0 or later.
328 --perf-no_read_workqueue, --perf-no_write_workqueue
330 Bypass dm-crypt internal workqueue and process read or write
331 requests synchronously.
332 NOTE: These options are available only for low-level dm-crypt
334 performance tuning, use only if you need a change to default
335 dm-crypt behaviour. Needs kernel 5.9 or later.
336 --test-passphrase
338 Do not activate the device, just verify passphrase. The device
339 mapping name is not mandatory if this option is used.
340 --header <device or file storing the LUKS header>
342 Specify detached (separated) metadata device or file where the
343 header is stored.
344 WARNING: There is no check whether the ciphertext device specified
346 actually belongs to the header given. In fact, you can specify an
347 arbitrary device as the ciphertext device with the --header option.
348 Use with care.
349 --disable-external-tokens
351 Disable loading of plugins for external LUKS2 tokens.
352 --disable-locks
354 Disable lock protection for metadata on disk. This option is valid
355 only for LUKS2 and ignored for other formats.
356 WARNING: Do not use this option unless you run cryptsetup in a
358 restricted environment where locking is impossible to perform
359 (where /run directory cannot be used).
360 --disable-keyring
362 Do not load volume key in kernel keyring and store it directly in
363 the dm-crypt target instead. This option is supported only for the
364 LUKS2 type.
365 --token-id
367 Specify what token to use and allow token PIN prompt to take
368 precedence over interative keyslot passphrase prompt. If omitted,
369 all available tokens (not protected by PIN) will be checked before
370 proceeding further with passphrase prompt.
371 --token-only
373 Do not proceed further with action if token based keyslot unlock
374 failed. Without the option, action asks for passphrase to proceed
375 further.
376 It allows LUKS2 tokens protected by PIN to take precedence over
378 interactive keyslot passphrase prompt.
379 --token-type type
381 Restrict tokens eligible for operation to specific token type.
382 Mostly useful when no --token-id is specified.
383 It allows LUKS2 type tokens protected by PIN to take precedence
385 over interactive keyslot passphrase prompt.
386 --sector-size bytes
388 Set encryption sector size for use with plain device type. It must
389 be power of two and in range 512 - 4096 bytes. The default mode is
390 512 bytes.
391 Note that if sector size is higher than underlying device hardware
393 sector, using this option can increase risk on incomplete sector
394 writes during a power fail.
395 Increasing sector size from 512 bytes to 4096 bytes can provide
397 better performance on most of the modern storage devices and also
398 with some hw encryption accelerators.
399 --iv-large-sectors
401 Count Initialization Vector (IV) in larger sector size (if set)
402 instead of 512 bytes sectors. This option can be used only with
403 plain device type.
404 NOTE: This option does not have any performance or security impact,
406 use it only for accessing incompatible existing disk images from
407 other systems that require this option.
408 --persistent
410 If used with LUKS2 devices and activation commands like open or
411 refresh, the specified activation flags are persistently written
412 into metadata and used next time automatically even for normal
413 activation. (No need to use cryptab or other system configuration
414 files.)
415 If you need to remove a persistent flag, use --persistent without
417 the flag you want to remove (e.g. to disable persistently stored
418 discard flag, use --persistent without --allow-discards).
419 Only --allow-discards, --perf-same_cpu_crypt,
421 --perf-submit_from_crypt_cpus, --perf-no_read_workqueue,
422 --perf-no_write_workqueue and --integrity-no-journal can be stored
423 persistently.
424 --refresh
426 Refreshes an active device with new set of parameters. See
427 cryptsetup-refresh(8) for more details.
428 --unbound
430 Allowed only together with --test-passphrase parameter, it allows
431 one to test passphrase for unbound LUKS2 keyslot. Otherwise,
432 unbound keyslot passphrase can be tested only when specific keyslot
433 is selected via --key-slot parameter.
434 --tcrypt-hidden, --tcrypt-system, --tcrypt-backup
436 Specify which TrueCrypt on-disk header will be used to open the
437 device. See TCRYPT section in cryptsetup(8) for more info.
438 --veracrypt
440 This option is ignored as VeraCrypt compatible mode is supported by
441 default.
442 --disable-veracrypt
444 This option can be used to disable VeraCrypt compatible mode (only
445 TrueCrypt devices are recognized). Only for TCRYPT extension. See
446 TCRYPT section in cryptsetup(8) for more info.
447 --veracrypt-pim, --veracrypt-query-pim
449 Use a custom Personal Iteration Multiplier (PIM) for VeraCrypt
450 device. See TCRYPT section in cryptsetup(8) for more info.
451 --serialize-memory-hard-pbkdf
453 Use a global lock to serialize unlocking of keyslots using
454 memory-hard PBKDF.
455 NOTE: This is (ugly) workaround for a specific situation when
457 multiple devices are activated in parallel and system instead of
458 reporting out of memory starts unconditionally stop processes using
459 out-of-memory killer.
460 DO NOT USE this switch until you are implementing boot environment
462 with parallel devices activation!
463 --batch-mode, -q
465 Suppresses all confirmation questions. Use with care!
466 If the --verify-passphrase option is not specified, this option
468 also switches off the passphrase verification.
469 --debug or --debug-json
471 Run in debug mode with full diagnostic logs. Debug output lines are
472 always prefixed by #.
473 If --debug-json is used, additional LUKS2 JSON data structures are
475 printed.
476 --version, -V
478 Show the program version.
479 --usage
481 Show short option help.
482 --help, -?
484 Show help text and default parameters.
485
487 Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
488 in Issues project section
489 <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
490 Please attach output of the failed command with --debug option added.
492
494 Cryptsetup FAQ
495 <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
496 cryptsetup(8), integritysetup(8) and veritysetup(8)
498
500 Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
501cryptsetup 2.6.1 2023-02-10 CRYPTSETUP-OPEN(8)