# cryptsetup-fvault2Open - open an encrypted device and create a mapping wi... - man(8) - [phpMan] [_CRYPTSETUP-OPEN_(8)](https://www.chedong.com/phpMan.php/man/CRYPTSETUP-OPEN/8/markdown) Maintenance Commands [_CRYPTSETUP-OPEN_(8)](https://www.chedong.com/phpMan.php/man/CRYPTSETUP-OPEN/8/markdown) ## NAME cryptsetup-open, cryptsetup-create, cryptsetup-plainOpen, cryptsetup-luksOpen, cryptsetup- loopaesOpen, cryptsetup-tcryptOpen, cryptsetup-bitlkOpen, cryptsetup-fvault2Open - open an encrypted device and create a mapping with a specified name ## SYNOPSIS **cryptsetup _**open_ **--type [] ** ## DESCRIPTION Opens (creates a mapping with) backed by device . Device type can be _plain_, _luks_ (default), _luks1_, _luks2_, _loopaes_ or _tcrypt_. For backward compatibility there are **open **command aliases: **create **(argument-order ): open --type plain **plainOpen**: open --type plain **luksOpen**: open --type luks **loopaesOpen**: open --type loopaes **tcryptOpen**: open --type tcrypt **bitlkOpen**: open --type bitlk ** **are type specific and are described below for individual device types. For **create**, the order of the and options is inverted for historical reasons, all other aliases use the standard ** **order. **PLAIN** **open --type plain **--cipher --key-size --hash plainOpen (**old syntax**) create (**OBSOLETE syntax**) Opens (creates a mapping with) backed by device . **WARNING: **You should always specify options **--cipher**, **--key-size **and (if no keyfile is used) then also **--hash **to avoid incompatibility as default values can be different in older cryptsetup versions. ** **can be [--hash, --cipher, --verify-passphrase, --sector-size, --key-file, --keyfile-size, --keyfile-offset, --key-size, --offset, --skip, --device-size, --size, --readonly, --shared, --allow-discards, --refresh, --timeout, --verify-passphrase, --iv-large-sectors]. Example: 'cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --hash sha256 /dev/sda10 e1' maps the raw encrypted device /dev/sda10 to the mapped (decrypted) device /dev/mapper/e1, which can then be mounted, fsck-ed or have a filesystem created on it. **LUKS** ### open open --type (**explicit version request**) luksOpen (**old syntax**) Opens the LUKS device and sets up a mapping after successful verification of the supplied passphrase. First, the passphrase is searched in LUKS2 tokens unprotected by PIN. If such token does not exist (or fails to unlock keyslot) and also the passphrase is not supplied via --key-file, the command prompts for passphrase interactively. If there is valid LUKS2 token but it requires PIN to unlock assigned keyslot, it is not used unless one of following options is added: --token-only, --token-type where type matches desired PIN protected token or --token-id with id matching PIN protected token. ** **can be [--key-file, --keyfile-offset, --keyfile-size, --readonly, --test-passphrase, --allow-discards, --header, --key-slot, --volume-key-file, --token-id, --token-only, --token-type, --disable-external-tokens, --disable-keyring, --disable-locks, --type, --refresh, --serialize-memory-hard-pbkdf, --unbound, --tries, --timeout, --verify-passphrase, --persistent, --volume-key-keyring, --link-vk-to-keyring, --external-tokens-path]. ### loopAES ### open --type loopaes --key-file loopaesOpen --key-file (**old syntax**) Opens the loop-AES and sets up a mapping . If the key file is encrypted with GnuPG, then you have to use --key-file=- and decrypt it before use, e.g., like this: gpg --decrypt | cryptsetup loopaesOpen --key-file=- **WARNING: **The loop-AES extension cannot use the direct input of the key file on the real terminal because the keys are separated by end-of-line and only part of the multi-key file would be read. If you need it in script, just use the pipe redirection: echo $keyfile | cryptsetup loopaesOpen --key-file=- Use **--keyfile-size **to specify the proper key length if needed. Use **--offset **to specify device offset. Note that the units need to be specified in number of 512 byte sectors. Use **--skip **to specify the IV offset. If the original device used an offset and but did not use it in IV sector calculations, you have to explicitly use **--skip 0 **in addition to the offset parameter. Use **--hash **to override the default hash function for passphrase hashing (otherwise it is detected according to key size). ** **can be [--cipher, --key-file, --keyfile-size, --keyfile-offset, --key-size, --offset, --skip, --hash, --readonly, --allow-discards, --refresh]. ### TrueCrypt and VeraCrypt ### open --type tcrypt tcryptOpen (**old syntax**) Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) and sets up a mapping . ** **can be [--key-file, --tcrypt-hidden, --tcrypt-system, --tcrypt-backup, --readonly, --test-passphrase, --allow-discards, --veracrypt (ignored), --disable-veracrypt, --veracrypt-pim, --veracrypt-query-pim, --header, --cipher, --hash, --tries, --timeout, --verify-passphrase]. The keyfile parameter allows a combination of file content with the passphrase and can be repeated. Note that using keyfiles is compatible with TCRYPT and is different from LUKS keyfile logic. If **--cipher **or **--hash **options are used, only cipher chains or PBKDF2 variants with the specified hash algorithms are checked. This could speed up unlocking the device (but also it reveals some information about the container). If you use **--header **in combination with hidden or system options, the header file must contain specific headers on the same positions as the original encrypted container. **WARNING: **Option **--allow-discards **cannot be combined with option **--tcrypt-hidden**. For normal mapping, it can cause the **destruction of hidden volume **(hidden volume appears as unused space for outer volume so this space can be discarded). ### BitLocker ### open --type bitlk bitlkOpen (**old syntax**) Opens the BITLK (a BitLocker compatible) and sets up a mapping . ** **can be [--key-file, --keyfile-offset, --keyfile-size, --key-size, --readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, --timeout, --verify-passphrase]. Note that **--test-passphrase **doesn’t work with **--volume-key-file **because we cannot check whether the provided volume key is correct for this device or not. When using **--volume-key-file **the device will be opened even if the provided key is not correct. ### FileVault2 ### open --type fvault2 fvault2Open (**old syntax**) Opens the FVAULT2 (a FileVault2 compatible) and sets up a mapping . ** **can be [--key-file, --keyfile-offset, --keyfile-size, --key-size, --readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, --timeout, --verify-passphrase]. ## OPTIONS ### --type Specifies required device type, for more info read _BASIC_ _ACTIONS_ section in [**cryptsetup**(8)](https://www.chedong.com/phpMan.php/man/cryptsetup/8/markdown). **--hash, -h _**_ Specifies the passphrase hash. Applies to _plain_ and _loopaes_ device types only. For _tcrypt_ device type, it restricts checked PBKDF2 variants when looking for header. **--cipher, -c _**_ Set the cipher specification string for _plain_ device type. For _tcrypt_ device type it restricts checked cipher chains when looking for header. _cryptsetup_ _--help_ shows the compiled-in defaults. If a hash is part of the cipher specification, then it is used as part of the IV generation. For example, ESSIV needs a hash function, while "plain64" does not and hence none is specified. For XTS mode you can optionally set a key size of 512 bits with the -s option. Key size for XTS mode is twice that for other modes for the same security level. ### --verify-passphrase, -y When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Advised when creating a _plain_ type mapping for the first time. Ignored on input from file or stdin. **--key-file, -d _**name_ Read the passphrase from file. If the name given is "-", then the passphrase will be read from stdin. In this case, reading will not stop at newline characters. **NOTE: **With _plain_ device type, the passphrase obtained via --key-file option is passed directly in dm-crypt. Unlike the interactive mode (stdin) where digest (--hash option) of the passphrase is passed in dm-crypt instead. See section _NOTES_ _ON_ _PASSPHRASE_ _PROCESSING_ in [**cryptsetup**(8)](https://www.chedong.com/phpMan.php/man/cryptsetup/8/markdown) for more information. **--keyfile-offset _**value_ Skip _value_ bytes at the beginning of the key file. **--keyfile-size, -l _**value_ Read a maximum of _value_ bytes from the key file. The default is to read the whole file up to the compiled-in maximum that can be queried with --help. Supplying more data than the compiled-in maximum aborts the operation. This option is useful to cut trailing newlines, for example. If --keyfile-offset is also given, the size count starts after the offset. ### --volume-key-file, --master-key-file (OBSOLETE alias) Use a volume key stored in a file. This allows one to open _luks_ and _bitlk_ device types without giving a passphrase. **--volume-key-keyring _**_ Use a volume key stored in a keyring. This allows one to open _luks_ and device types without giving a passphrase. The key and associated type has to be readable from userspace so that volume key digest may be verified in before activation. The __ uses keyctl-compatible syntax. This can either be a numeric key ID or a string name in the format _%:_. See also **KEY IDENTIFIERS **section of [**keyctl**(1)](https://www.chedong.com/phpMan.php/man/keyctl/1/markdown). When no _%:_ prefix is specified we assume the key type is _user_ (default type). ### --key-slot, -S <0-N> This option selects a specific key-slot to compare the passphrase against. If the given passphrase would only match a different key-slot, the operation fails. The maximum number of key slots depends on the LUKS version. LUKS1 can have up to 8 key slots. LUKS2 can have up to 32 key slots based on key slot area size and key size, but a valid key slot ID can always be between 0 and 31 for LUKS2. **--key-size, -s _**bits_ Sets key size in _bits_. The argument has to be a multiple of 8. The possible key-sizes are limited by the cipher and mode used. See /proc/crypto for more information. Note that key-size in /proc/crypto is stated in bytes. This option can be used for _plain_ device type only. ### --size, -b Set the size of the device in sectors of 512 bytes. Usable only with _plain_ device type. ### --offset, -o Start offset in the backend device in 512-byte sectors. This option is only relevant with plain or loopaes device types. ### --skip, -p Start offset used in IV calculation in 512-byte sectors (how many sectors of the encrypted data to skip at the beginning). This option is only relevant with plain or loopaes device types. Hence, if --offset _n_, and --skip _s_, sector _n_ (the first sector of the encrypted device) will get a sector number of _s_ for the IV calculation. **--device-size _**size[units]_ Instead of real device size, use specified value. Usable only with _plain_ device type. If no unit suffix is specified, the size is in bytes. Unit suffix can be S for 512 byte sectors, K/M/G/T (or KiB,MiB,GiB,TiB) for units with 1024 base or KB/MB/GB/TB for 1000 base (SI scale). ### --readonly, -r set up a read-only mapping. ### --shared Creates an additional mapping for one common ciphertext device. Arbitrary mappings are supported. This option is only relevant for the _plain_ device type. Use --offset, --size and --skip to specify the mapped area. ### --timeout, -t The number of seconds to wait before timeout on passphrase input via terminal. It is relevant every time a passphrase is asked. It has no effect if used in conjunction with --key-file. This option is useful when the system should not stall if the user does not input a passphrase, e.g. during boot. The default is a value of 0 seconds, which means to wait forever. ### --tries, -T How often the input of the passphrase shall be retried. The default is 3 tries. ### --allow-discards Allow the use of discard (TRIM) requests for the device. This is also not supported for LUKS2 devices with data integrity protection. **WARNING: **This command can have a negative security impact because it can make filesystem-level operations visible on the physical device. For example, information leaking filesystem type, used space, etc. may be extractable from the physical device if the discarded blocks can be located later. If in doubt, do not use it. A kernel version of 3.1 or later is needed. For earlier kernels, this option is ignored. ### --perf-same_cpu_crypt Perform encryption using the same cpu that IO was submitted on. The default is to use an unbound workqueue so that encryption work is automatically balanced between available CPUs. **NOTE: **This option is available only for low-level dm-crypt performance tuning, use only if you need a change to default dm-crypt behaviour. Needs kernel 4.0 or later. ### --perf-submit_from_crypt_cpus Disable offloading writes to a separate thread after encryption. There are some situations where offloading write bios from the encryption threads to a single thread degrades performance significantly. The default is to offload write bios to the same thread. **NOTE: **This option is available only for low-level dm-crypt performance tuning, use only if you need a change to default dm-crypt behaviour. Needs kernel 4.0 or later. ### --perf-no_read_workqueue, --perf-no_write_workqueue Bypass dm-crypt internal workqueue and process read or write requests synchronously. **NOTE: **These options are available only for low-level dm-crypt performance tuning, use only if you need a change to default dm-crypt behaviour. Needs kernel 5.9 or later. ### --test-passphrase Do not activate the device, just verify passphrase. The device mapping name is not mandatory if this option is used. ### --header Specify detached (separated) metadata device or file where the header is stored. **WARNING: **There is no check whether the ciphertext device specified actually belongs to the header given. In fact, you can specify an arbitrary device as the ciphertext device with the --header option. Use with care. ### --disable-external-tokens Disable loading of plugins for external LUKS2 tokens. ### --disable-locks Disable lock protection for metadata on disk. This option is valid only for LUKS2 and ignored for other formats. **WARNING: **Do not use this option unless you run cryptsetup in a restricted environment where locking is impossible to perform (where /run directory cannot be used). ### --disable-keyring Do not load volume key in kernel keyring and store it directly in the dm-crypt target instead. This option is supported only for the LUKS2 type. **--link-vk-to-keyring _**::_ Link volume key in a keyring with specified key name. The volume key is linked only if requested action is successfully finished. __ string has to contain existing kernel keyring description. The keyring name may be optionally prefixed with "%:" or "%keyring:" type descriptions. Or, the keyring may also be specified directly by numeric key id. Also special keyring notations starting with "@" may be used to select existing predefined kernel keyrings. The string "::" is delimiter used to separate keyring description and key description. __ part describes key type and key name of volume key linked in the keyring described in __. The type may be specified by adding "%:" prefix in front of key name. If type is missing default _user_ type is applied. If the key of same name and same type already exists (already linked in the keyring) it will get replaced in the process. See also **KEY IDENTIFIERS **section of [**keyctl**(1)](https://www.chedong.com/phpMan.php/man/keyctl/1/markdown). ### --token-id Specify what token to use and allow token PIN prompt to take precedence over interactive keyslot passphrase prompt. If omitted, all available tokens (not protected by PIN) will be checked before proceeding further with passphrase prompt. ### --token-only Do not proceed further with action if token based keyslot unlock failed. Without the option, action asks for passphrase to proceed further. It allows LUKS2 tokens protected by PIN to take precedence over interactive keyslot passphrase prompt. **--token-type _**type_ Restrict tokens eligible for operation to specific token _type_. Mostly useful when no --token-id is specified. It allows LUKS2 _type_ tokens protected by PIN to take precedence over interactive keyslot passphrase prompt. **--sector-size _**bytes_ Set encryption sector size for use with _plain_ device type. It must be power of two and in range 512 - 4096 bytes. The default mode is 512 bytes. Note that if sector size is higher than underlying device hardware sector, using this option can increase risk on incomplete sector writes during a power fail. Increasing sector size from 512 bytes to 4096 bytes can provide better performance on most of the modern storage devices and also with some hw encryption accelerators. ### --iv-large-sectors Count Initialization Vector (IV) in larger sector size (if set) instead of 512 bytes sectors. This option can be used only with _plain_ device type. **NOTE: **This option does not have any performance or security impact, use it only for accessing incompatible existing disk images from other systems that require this option. ### --persistent If used with LUKS2 devices and activation commands like _open_ or _refresh_, the specified activation flags are persistently written into metadata and used next time automatically even for normal activation. (No need to use cryptab or other system configuration files.) If you need to remove a persistent flag, use _--persistent_ without the flag you want to remove (e.g. to disable persistently stored discard flag, use _--persistent_ without _--allow-discards_). Only _--allow-discards_, _--perf-same_cpu_crypt_, _--perf-submit_from_crypt_cpus_, _--perf-no_read_workqueue_, _--perf-no_write_workqueue_ and _--integrity-no-journal_ can be stored persistently. ### --refresh Refreshes an active device with new set of parameters. See [**cryptsetup-refresh**(8)](https://www.chedong.com/phpMan.php/man/cryptsetup-refresh/8/markdown) for more details. ### --unbound Allowed only together with --test-passphrase parameter, it allows one to test passphrase for unbound LUKS2 keyslot. Otherwise, unbound keyslot passphrase can be tested only when specific keyslot is selected via --key-slot parameter. **--tcrypt-hidden**, **--tcrypt-system**, **--tcrypt-backup** Specify which TrueCrypt on-disk header will be used to open the device. See _TCRYPT_ section in [**cryptsetup**(8)](https://www.chedong.com/phpMan.php/man/cryptsetup/8/markdown) for more info. ### --veracrypt This option is ignored as VeraCrypt compatible mode is supported by default. ### --disable-veracrypt This option can be used to disable VeraCrypt compatible mode (only TrueCrypt devices are recognized). Only for TCRYPT extension. See _TCRYPT_ section in [**cryptsetup**(8)](https://www.chedong.com/phpMan.php/man/cryptsetup/8/markdown) for more info. **--veracrypt-pim**, **--veracrypt-query-pim** Use a custom Personal Iteration Multiplier (PIM) for VeraCrypt device. See _TCRYPT_ section in [**cryptsetup**(8)](https://www.chedong.com/phpMan.php/man/cryptsetup/8/markdown) for more info. ### --serialize-memory-hard-pbkdf Use a global lock to serialize unlocking of keyslots using memory-hard PBKDF. **NOTE: **This is (ugly) workaround for a specific situation when multiple devices are activated in parallel and system instead of reporting out of memory starts unconditionally stop processes using out-of-memory killer. **DO NOT USE **this switch until you are implementing boot environment with parallel devices activation! **--external-tokens-path _**absolute_path_ Override system directory path where cryptsetup searches for external token handlers (or token plugins). It must be absolute path (starting with '/' character). ### --batch-mode, -q Suppresses all confirmation questions. Use with care! If the --verify-passphrase option is not specified, this option also switches off the passphrase verification. ### --debug or --debug-json Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by **#**. If --debug-json is used, additional LUKS2 JSON data structures are printed. ### --version, -V Show the program version. ### --usage Show short option help. ### --help, -? Show help text and default parameters. ## REPORTING BUGS Report bugs at **cryptsetup mailing list **<> or in **Issues project** **section **<>. Please attach output of the failed command with --debug option added. ## SEE ALSO **Cryptsetup FAQ **<> [**cryptsetup**(8)](https://www.chedong.com/phpMan.php/man/cryptsetup/8/markdown), [**integritysetup**(8)](https://www.chedong.com/phpMan.php/man/integritysetup/8/markdown) and [**veritysetup**(8)](https://www.chedong.com/phpMan.php/man/veritysetup/8/markdown) ## CRYPTSETUP Part of **cryptsetup project **<>. cryptsetup 2.7.0 2024-11-14 [_CRYPTSETUP-OPEN_(8)](https://www.chedong.com/phpMan.php/man/CRYPTSETUP-OPEN/8/markdown)