--- name: "cryptsetup-open" section: "8" platform: "linux" package: "cryptsetup" version: "2.8.8-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/cryptsetup-open" --- # cryptsetup-open(8) open an encrypted device and create a mapping with a specified name ## 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 \.* *You should always specify options --cipher, --key-size and (if no keyfile or keyring is used) then also --hash to avoid incompatibility, as default values can differ in older cryptsetup versions.* *The plain format also allows retrieving a volume key from a kernel keyring specified by --volume-key-keyring.* *The key in the kernel keyring must be configured before issuing cryptsetup commands, as cryptsetup does not upload any keys to the keyring in plain mode.* *For subsequent commands (like resize), the user must ensure that the key in the keyring is unchanged.* *Otherwise, reloading the key can cause data corruption after an unexpected key change.* **\** *can be \[--hash, --cipher, --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, --volume-key-keyring\].* **EXAMPLES:** *To map the encrypted device /dev/sda10 to the decrypted device /dev/mapper/e1, you can use:* **cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --hash sha256 /dev/sda10 e1** *The decrypted device can then be used as a normal block device to mount a filesystem.* *To map a device with a volume key in the preconfigured trusted or encrypted keyring, you need to specify the keyring with the key and remove the hash specification, for example, to use* **%trusted:mykey***:* **cryptsetup open --type plain /dev/sda10 e1 --volume-key-keyring=%trusted:mykey --cipher aes-xts-plain64 --key-size 256** *Note that the key size must match the preconfigured key in the keyring.* ### 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 a token does not exist (or fails to unlock keyslot) and the passphrase is not supplied via --key-file, the command prompts for passphrase interactively.* *If there is a valid LUKS2 token but it requires a PIN to unlock the assigned keyslot, it is not used unless one of the following options is added: --token-only,* *--token-type where type matches the desired PIN-protected token or --token-id with id matching the 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=- \ \***.* *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 terms of 512-byte sectors.* *Use --skip to specify the IV offset.* *If the original device used an offset but did not use it in IV sector calculations, you must 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 \.* *The --key-file option allows a combination of file content with the passphrase* *The --key-file option can be repeated.* *Note that using keyfiles differs 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 reveals some information about the container).* *If you use --header in combination with hidden or system options, the header file must contain specific headers in the same positions as the original encrypted container.* *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).* **\** *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\].* ### BitLocker **open --type bitlk \ \**\ *bitlkOpen \ \ (old syntax)* *Opens the BITLK (a BitLocker compatible) \ and sets up a mapping \.* *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.* *When using --volume-key-file, the device will be opened even if the provided key is incorrect.* **\** *can be \[--key-file, --keyfile-offset, --keyfile-size, --key-size, --readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, --timeout, --verify-passphrase\].* ### 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 - **--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.* **--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.* **--cipher***,* **-c** *\* *Set the cipher specification string for the plain device type.* *For the tcrypt device type, it restricts checked cipher chains when looking for the 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.* **--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.* **--device-size** *size\[units\]* *Instead of the real device size, use the 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).* - **--disable-external-tokens** *Disable loading of plugins for external LUKS2 tokens.* - **--disable-keyring** *Do not load the volume key in the kernel keyring; store it directly in the dm-crypt target instead.* *This option is supported only for the LUKS2 type.* - **--disable-locks** *Disable lock protection for metadata on disk.* *This option is valid only for LUKS2 and is 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-veracrypt** *This option can be used to disable VeraCrypt compatible mode (only TrueCrypt devices are recognized).* *See the TCRYPT section in* **cryptsetup***(8) for more info.* **--external-tokens-path** *\* *Override the system directory path where cryptsetup searches for external token handlers (or token plugins).* *It must be an absolute path (starting with '/' character).* **--hash***,* **-h** *\* *Specifies the passphrase hash.* *Applies to plain and loopaes device types only.* *For the tcrypt device type, it restricts the checked PBKDF2 variants when looking for the header.* **--header** *\* *Specify a 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.* **--help***,* **-?** *Show help text and default parameters.* - **--iv-large-sectors** *Count Initialization Vector (IV) in larger sector size (if set) instead of 512-byte sectors.* *This option can be used only with the plain device type.* *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.* **--key-description** *text* *Set the key description in the keyring that will be used for passphrase retrieval.* **--key-file***,* **-d** *file* *Read the passphrase from the file.* *If the name given is "-", then the passphrase will be read from stdin.* *In this case, reading will not stop at newline characters.* *With plain device type, the passphrase obtained via --key-file option is passed directly in dm-crypt.* *Unlike the interactive mode (stdin), where the digest of the passphrase is passed in dm-crypt instead.* *See section NOTES ON PASSPHRASE PROCESSING in* **cryptsetup***(8) 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.* **--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 the key size in /proc/crypto is stated in bytes.* *This option can be used for plain and luks devices.* *For LUKS2 devices in reencryption, you may use the parameter twice to specify both old and new volume key sizes.* *Each --key-size option corresponds to the respective --volume-key-file parameter (also allowed to be used up to two times).* **--key-slot***,* **-S** *\<0-N\>* *This option selects a specific keyslot to compare the passphrase against.* *If the given passphrase would only matches a different keyslot, the operation fails.* *The maximum number of keyslots depends on the LUKS version.* *LUKS1 can have up to 8 keyslots.* *LUKS2 can have up to 32 keyslots based on keyslot area size and key size, but a valid keyslot ID can always be between 0 and 31 for LUKS2.* **--link-vk-to-keyring** *\::\* *Link the volume key in a keyring with the specified key name.* *The volume key is linked only if the requested action is successfully finished (with --test-passphrase, the verified volume key is linked in a keyring without taking further action).* *The \ string has to contain the 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 a delimiter used to separate the 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 a "%\:" prefix in front of the key name.* *If the type is missing, the default user type is applied.* *If the key of the same name and type already exists (already linked in the keyring), it will get replaced in the process.* *See also the* **KEY IDENTIFIERS** *section of* **keyctl***(1).* **--offset***,* **-o** *\* *Start offset in the backend device in 512-byte sectors.* *This option is only relevant with plain or loopaes device types.* - **--perf-high\_priority** *Set dm-crypt workqueues and the writer thread to high priority.* *This improves throughput and latency of dm-crypt while degrading the general responsiveness of the system.* *This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.* *Needs kernel 6.10 or later.* **--perf-no\_read\_workqueue***,* **--perf-no\_write\_workqueue** *Bypass dm-crypt internal workqueue and process read or write requests synchronously.* *These options are available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.* *Needs kernel 5.9 or later.* - **--perf-same\_cpu\_crypt** *Perform encryption using the same CPU on which that IO was submitted.* *The default is to use an unbound workqueue so that encryption work is automatically balanced between available CPUs.* *This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.* - **--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.* *This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.* - **--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 the 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.* **--readonly***,* **-r** *Set up a read-only mapping.* - **--refresh** *Refreshes an active device with a new set of parameters.* *See* **cryptsetup-refresh***(8) for more details.* **--sector-size** *bytes* *Set encryption sector size for use with plain device type.* *It must be a power of two and in the 512 - 4096 bytes range.* *The default encryption sector size is 512 bytes.* *Increasing sector size from 512 to 4096 bytes can provide better performance on most modern storage devices and with some hardware encryption accelerators.* *Note that using a sector size larger than the underlying storage device’s physical sector size may result in data corruption during unexpected power failures.* *A power failure during write operations may result in only partial completion of the encryption sector write, leaving encrypted data in an inconsistent state that cannot be properly decrypted.* - **--serialize-memory-hard-pbkdf** *Use a global lock to serialize unlocking of keyslots using memory-hard PBKDF.* *This is a workaround for a specific situation when multiple devices are activated in parallel, and the system, instead of reporting out of memory, starts unconditionally stop processes using the out-of-memory killer.* **DO NOT USE** *this switch until you are implementing the boot environment with parallel devices activation!* - **--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.* **--size***,* **-b** *\* *Set the size of the device in sectors of 512 bytes.* *Usable only with plain device type.* **--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.* **--tcrypt-backup***,* **--tcrypt-hidden***,* **--tcrypt-system** *Specify which TrueCrypt on-disk header will be used to open the device.* *See the TCRYPT section in* **cryptsetup***(8) for more info.* *Using a system-encrypted device with the --tcrypt-system option requires specific settings to work as expected.* *TrueCrypt/VeraCrypt supports full system encryption (only a partition table is not encrypted) or system partition encryption (only a system partition is encrypted).* *The metadata header then contains the offset and size of the encrypted area.* *Cryptsetup needs to know the specific partition offset to calculate encryption parameters.* *To properly map a partition, you must specify a real partition device so cryptsetup can calculate this offset.* *While you can use a full device as a parameter (/dev/sdb), always prefer to specify the partition you want to map (/dev/sdb1), as only the system partition mode can be detected this way.* *For mapping images (stored in a file), you can use the additional --header option with the real partition device.* *If the --header is used (and it is different from the data image), cryptsetup expects that the data image contains a snapshot of the data partition only.* *If --header is not used (or points to the same image), cryptsetup expects that the image contains a full disk (including the partition table).* *This can map a full encrypted area that is not directly mountable as a filesystem.* *Please prefer creating a loop device with partitions (***losetup -P***, see* **losetup***(8) man page) and use a real partition (/dev/loopXp1) as the device parameter.* - **--test-passphrase** *Do not activate the device, just verify the passphrase.* *The device mapping name is not mandatory if this option is used.* **--timeout***,* **-t** *seconds* *The number of seconds to wait before a 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.* - **--token-id** *Specify what token to use and allow the token PIN prompt to take precedence over the interactive keyslot passphrase prompt.* *If omitted, all available tokens (not protected by PIN) will be checked before proceeding further with the passphrase prompt.* - **--token-only** *Do not proceed further with the action if the token-based keyslot unlock failed.* *Without the option, the action asks for a passphrase to proceed further.* *It allows LUKS2 tokens protected by PIN to take precedence over the interactive keyslot passphrase prompt.* **--token-type** *type* *Restrict tokens eligible for operation to a specific token type.* *Mostly useful when no --token-id is specified.* *It allows LUKS2 type tokens protected by PIN to take precedence over the interactive keyslot passphrase prompt.* **--tries***,* **-T** *How often the input of the passphrase shall be retried.* *The default is 3 tries.* **--type** *type* *Specifies required device type, for more info, read the BASIC ACTIONS section in* **cryptsetup***(8).* - **--unbound** *Allowed only together with --test-passphrase parameter, it allows one to test the passphrase for an unbound LUKS2 keyslot.* *Otherwise, an unbound keyslot passphrase can be tested only when a specific keyslot is selected via --key-slot parameter.* - **--usage** *Show short option help.* - **--veracrypt** *This option is ignored as VeraCrypt compatible mode is supported by default.* **--veracrypt-pim***,* **--veracrypt-query-pim** *Use a custom Personal Iteration Multiplier (PIM) for the VeraCrypt device.* *See the TCRYPT section in* **cryptsetup***(8) for more info.* **--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.* **--version***,* **-V** *Show the program version.* **--volume-key-file** *file, --master-key-file 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.* *For devices in reencryption, the option may be used twice to specify both old and new volume keys.* *When using the option twice, make sure you pair each --volume-key-file option with the respective --key-size parameter as well.* **--volume-key-keyring** *\* *Use a volume key stored in a keyring.* *This allows one to open luks and plain device types without giving a passphrase.* *For LUKS, the key and associated type have to be readable from userspace so that the volume key digest may be verified before activation.* *For devices in reencryption, the option may be used twice to specify both old and new volume keys.* *For PLAIN type, the user must ensure that the key in the keyring is unchanged since activation.* *Otherwise, reloading the key can cause data corruption after an unexpected key change.* *The \ uses keyctl-compatible syntax.* *This can either be a numeric key ID or a string name in the format %\:\.* *See also the* **KEY IDENTIFIERS** *section of* **keyctl***(1).* *When no %\: prefix is specified, we assume the key type is user (default type).* ## REPORTING BUGS *Report bugs at* *cryptsetup mailing list \* *or in* *Issues project section \.* *Please attach the output of the failed command with --debug option added.* ## SEE ALSO *Cryptsetup FAQ \* **cryptsetup***(8),* **integritysetup***(8) and* **veritysetup***(8)* ## CRYPTSETUP *Part of* *cryptsetup project \.*