cryptsetup-open(8) — Linux manual page


CRYPTSETUP-OPEN(8)        Maintenance Commands        CRYPTSETUP-OPEN(8)

NAME         top

       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         top

       cryptsetup open --type <device_type> [<options>] <device> <name>

DESCRIPTION         top

       Opens (creates a mapping with) <name> backed by device <device>.

       Device type can be plain, luks (default), luks1, luks2, loopaes
       or tcrypt.

       For backward compatibility there are open command aliases:

       create (argument-order <name> <device>): open --type plain
       plainOpen: open --type plain
       luksOpen: open --type luks
       loopaesOpen: open --type loopaes
       tcryptOpen: open --type tcrypt
       bitlkOpen: open --type bitlk

       <options> are type specific and are described below for
       individual device types. For create, the order of the <name> and
       <device> options is inverted for historical reasons, all other
       aliases use the standard <device> <name> order.

       open --type plain <device> <name>
       plainOpen <device> <name> (old syntax)
       create <name> <device> (OBSOLETE syntax)

       Opens (creates a mapping with) <name> backed by device <device>.

       <options> 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 /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.

       open <device> <name>
       open --type <luks1|luks2> <device> <name> (explicit version
       luksOpen <device> <name> (old syntax)

       Opens the LUKS device <device> and sets up a mapping <name> after
       successful verification of the supplied passphrase.

       First, the passphrase is searched in LUKS tokens. If it’s not
       found in any token and also the passphrase is not supplied via
       --key-file, the command prompts for it interactively.

       <options> 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].

       open --type loopaes <device> <name> --key-file <keyfile>
       loopaesOpen <device> <name> --key-file <keyfile> (old syntax)

       Opens the loop-AES <device> and sets up a mapping <name>.

       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 <keyfile> | cryptsetup loopaesOpen --key-file=-
       <device> <name>

       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=- <device>

       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

       Use --hash to override the default hash function for passphrase
       hashing (otherwise it is detected according to key size).

       <options> can be [--cipher, --key-file, --keyfile-size,
       --keyfile-offset, --key-size, --offset, --skip, --hash,
       --readonly, --allow-discards, --refresh].

   TrueCrypt and VeraCrypt
       open --type tcrypt <device> <name>
       tcryptOpen <device> <name> (old syntax)

       Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) <device>
       and sets up a mapping <name>.

       <options> 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).

       open --type bitlk <device> <name>
       bitlkOpen <device> <name> (old syntax)

       Opens the BITLK (a BitLocker compatible) <device> and sets up a
       mapping <name>.

       <options> can be [--key-file, --keyfile-offset, --keyfile-size,
       --key-size, --readonly, --test-passphrase, --allow-discards
       --volume-key-file, --tries, --timeout, --verify-passphrase].

       open --type fvault2 <device> <name>
       fvault2Open <device> <name> (old syntax)

       Opens the FVAULT2 (a FileVault2 compatible) <device> and sets up
       a mapping <name>.

       <options> can be [--key-file, --keyfile-offset, --keyfile-size,
       --key-size, --readonly, --test-passphrase, --allow-discards
       --volume-key-file, --tries, --timeout, --verify-passphrase].

OPTIONS         top

       --type <device-type>
           Specifies required device type, for more info read BASIC
           ACTIONS section in cryptsetup(8).

       --hash, -h <hash-spec>
           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 <cipher-spec>
           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

           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

           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)
           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.

       --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

           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 <number of 512 byte sectors>
           Set the size of the device in sectors of 512 bytes. Usable
           only with plain device type.

       --offset, -o <number of 512 byte sectors>
           Start offset in the backend device in 512-byte sectors. This
           option is only relevant with plain or loopaes device types.

       --skip, -p <number of 512 byte sectors>
           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

           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.

           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 <number of seconds>
           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

           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 the use of discard (TRIM) requests for the device. This
           is also not supported for LUKS2 devices with data integrity

           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.

           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

           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.

           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.

           Do not activate the device, just verify passphrase. The
           device mapping name is not mandatory if this option is used.

       --header <device or file storing the LUKS 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 loading of plugins for external LUKS2 tokens.

           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).

           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.

           Specify what token to use. If omitted, all available tokens
           will be checked before proceeding further with passphrase

           Do not proceed further with action if token based keyslot
           unlock failed. Without the option, action asks for passphrase
           to proceed further.

       --token-type type
           Restrict tokens eligible for operation to specific token
           type. Mostly useful when no --token-id is specified.

       --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.

           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.

           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

           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.

           Refreshes an active device with new set of parameters. See
           cryptsetup-refresh(8) for more details.

           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) for more

           This option is ignored as VeraCrypt compatible mode is
           supported by default.

           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) for more info.

       --veracrypt-pim, --veracrypt-query-pim
           Use a custom Personal Iteration Multiplier (PIM) for
           VeraCrypt device. See TCRYPT section in cryptsetup(8) for
           more info.

           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!

       --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.

           Show short option help.

       --help, -?
           Show help text and default parameters.

REPORTING BUGS         top

       Report bugs at cryptsetup mailing list
       <> or in Issues project section

       Please attach output of the failed command with --debug option

SEE ALSO         top

       Cryptsetup FAQ

       cryptsetup(8), integritysetup(8) and veritysetup(8)

CRYPTSETUP         top

       Part of cryptsetup project
       <>. This page is part of
       the Cryptsetup ((open-source disk encryption)) project.
       Information about the project can be found at 
       ⟨⟩. If you have a bug
       report for this manual page, send it to This
       page was obtained from the project's upstream Git repository
       ⟨⟩ on 2023-12-22. (At
       that time, the date of the most recent commit that was found in
       the repository was 2023-12-20.) If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

cryptsetup 2.6.1-git           2022-12-14             CRYPTSETUP-OPEN(8)

Pages that refer to this page: cryptsetup(8)