Linux "cryptsetup" Command Line Options and Examples

manage plain dm-crypt and LUKS encrypted volumes

cryptsetup is used to conveniently setup dm-crypt managed device-mapper mappings. These include plain dm-crypt volumes and LUKS vol‐ umes. The difference is that LUKS uses a metadata header and can hence offer more features than plain dm-crypt.

Usage:

cryptsetup

Command Line Options:

--verbose

Print more information on command execution.


                            cryptsetup --verbose ...

--debug

Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by '#'.


                            cryptsetup --debug ...

--type

Specifies required device type, for more info read BASIC COMMANDS section.


                            cryptsetup --type ...

--hash

Specifies the passphrase hash for open (for plain and loopaes device types).Specifies the hash used in the LUKS key setup scheme and volume key digest for luksFormat. The specified hash is used as hash-parameter for PBKDF2 and for the AF splitter.The specified hash name is passed to the compiled-in crypto backend. Different backends may support different hashes. ForluksFormat, the hash algorithm must provide at least 160 bits of output, which excludes, e.g., MD5. Do not use a non-cryptohash like "crc32" as this breaks security.Values compatible with old version of cryptsetup are "ripemd160" for open --type plain and "sha1" for luksFormat.Use cryptsetup --help to show the defaults.


                            cryptsetup --hash ...

--cipher

Set the cipher specification string.cryptsetup --help shows the compiled-in defaults. The current default in the distributed sources is "aes-cbc-essiv:sha256"for plain dm-crypt and "aes-xts-plain64" for LUKS.If a hash is part of the cipher specification, then it is used as part of the IV generation. For example, ESSIV needs a hashfunction, 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 othermodes for the same security level.XTS mode requires kernel 2.6.24 or later and plain64 requires kernel 2.6.33 or later. More information can be found in theFAQ.


                            cryptsetup --cipher ...

--verify-passphrase

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Advised when creating aregular mapping for the first time, or when running luksFormat. Ignored on input from file or stdin.


                            cryptsetup --verify-passphrase ...

--key-file

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 charac‐ters.With LUKS, passphrases supplied via --key-file are always the existing passphrases requested by a command, except in the caseof luksFormat where --key-file is equivalent to the positional key file argument.If you want to set a new passphrase via key file, you have to use a positional argument to luksAddKey.See section NOTES ON PASSPHRASE PROCESSING for more information.


                            cryptsetup --key-file ...

--keyfile-offset

Skip value bytes at the beginning of the key file. Works with all commands that accept key files.


                            cryptsetup --keyfile-offset ...

--keyfile-size

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 canbe 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 afterthe offset. Works with all commands that accept key files.


                            cryptsetup --keyfile-size ...

--new-keyfile-offset

Skip value bytes at the start when adding a new passphrase from key file with luksAddKey.


                            cryptsetup --new-keyfile-offset ...

--new-keyfile-size

Read a maximum of value bytes when adding a new passphrase from key file with luksAddKey. The default is to read the wholefile up to the compiled-in maximum length that can be queried with --help. Supplying more than the compiled in maximum abortsthe operation. When --new-keyfile-offset is also given, reading starts after the offset.


                            cryptsetup --new-keyfile-size ...

--master-key-file

Use a master key stored in a file.For luksFormat this allows creating a LUKS header with this specific master key. If the master key was taken from an existingLUKS header and all other parameters are the same, then the new header decrypts the data encrypted with the header the masterkey was taken from.WARNING: If you create your own master key, you need to make sure to do it right. Otherwise, you can end up with a low-entropyor otherwise partially predictable master key which will compromise security.For luksAddKey this allows adding a new passphrase without having to know an existing one.For open this allows one to open the LUKS device without giving a passphrase.


                            cryptsetup --master-key-file ...

--dump-master-key

For luksDump this option includes the master key in the displayed information. Use with care, as the master key can be used tobypass the passphrases, see also option --master-key-file.


                            cryptsetup --dump-master-key ...

--use-urandom

For luksFormat these options define which kernel random number generator will be used to create the master key (which is along-term key).See NOTES ON RANDOM NUMBER GENERATORS for more information. Use cryptsetup --help to show the compiled-in default random num‐ber generator.WARNING: In a low-entropy situation (e.g. in an embedded system), both selections are problematic. Using /dev/urandom canlead to weak keys. Using /dev/random can block a long time, potentially forever, if not enough entropy can be harvested bythe kernel.


                            cryptsetup --use-urandom ...

--key-slot

For LUKS operations that add key material, this options allows you to specify which key slot is selected for the new key.This option can be used for luksFormat, and luksAddKey.In addition, for open, this option selects a specific key-slot to compare the passphrase against. If the given passphrasewould only match a different key-slot, the operation fails.


                            cryptsetup --key-slot ...

--key-size

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 open --type plain or luksFormat. All other LUKS actions will use the key-size specified in theLUKS header. Use cryptsetup --help to show the compiled-in defaults.


                            cryptsetup --key-size ...

--size

Set the size of the device in sectors of 512 bytes. This option is only relevant for the open and resize actions.


                            cryptsetup --size ...

--offset

Start offset in the backend device in 512-byte sectors. This option is only relevant for the open action with plain orloopaes device types.


                            cryptsetup --offset ...

--skip

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 for the open action 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 theIV calculation.


                            cryptsetup --skip ...

--readonly

set up a read-only mapping.


                            cryptsetup --readonly ...

--shared

Creates an additional mapping for one common ciphertext device. Arbitrary mappings are supported. This option is only rele‐vant for the open --type plain action. Use --offset, --size and --skip to specify the mapped area.


                            cryptsetup --shared ...

--pbkdf

Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot. The PBKDF can be: pbkdf2 (for PBKDF2 accordingto RFC2898), argon2i for Argon2i or argon2id for Argon2id (see https://www.cryptolux.org/index.php/Argon2 for more info).For LUKS1, only PBKDF2 is accepted (no need to use this option). The default PBKDF2 for LUKS2 is set during compilation timeand is available in cryptsetup --help output.A PBKDF is used for increasing dictionary and brute-force attack cost for keyslot passwords. The parameters can be time, mem‐ory and parallel cost.For PBKDF2, only time cost (number of iterations) applies. For Argon2i/id, there is also memory cost (memory required duringthe process of key derivation) and parallel cost (number of threads that run in parallel during the key derivation.Note that increasing memory cost also increases time, so the final parameter values are measured by a benchmark. The benchmarktries to find iteration time (--iter-time) with required memory cost --pbkdf-memory. If it is not possible, the memory cost isdecreased as well. The parallel cost --pbkdf-parallel is constant, is is checked against available CPU cores (if not avail‐able, it is decreased) and the maximum parallel cost is 4.You can see all PBKDF parameters for particular LUKS2 keyslot with luksDump command.NOTE: If you do not want to use benchmark and want to specify all parameters directly, use --pbkdf-force-iterations with


                            cryptsetup --pbkdf ...

--iter-time

The number of milliseconds to spend with PBKDF passphrase processing. This option is only relevant for LUKS operations thatset or change passphrases, such as luksFormat or luksAddKey. Specifying 0 as parameter selects the compiled-in default.


                            cryptsetup --iter-time ...

--pbkdf-memory

Set the memory cost for PBKDF (for Argon2i/id the number represents kilobytes). Note that it is maximal value, PBKDF bench‐mark or available physical memory can decrease it. This option is not available for PBKDF2.


                            cryptsetup --pbkdf-memory ...

--pbkdf-parallel

Set the parallel cost for PBKDF (number of threads, up to 4). Note that it is maximal value, it is decreased automatically ifCPU online count is lower. This option is not available for PBKDF2.


                            cryptsetup --pbkdf-parallel ...

--pbkdf-force-iterations

Avoid PBKDF benchmark and set time cost (iterations) directly. It can be used for LUKS/LUKS2 device only. See --pbkdf optionfor more info.


                            cryptsetup --pbkdf-force-iterations ...

--batch-mode

Suppresses all confirmation questions. Use with care!If the -y option is not specified, this option also switches off the passphrase verification for luksFormat.


                            cryptsetup --batch-mode ...

--progress-frequency

Print separate line every <seconds> with wipe progress.


                            cryptsetup --progress-frequency ...

--timeout

The number of seconds to wait before timeout on passphrase input via terminal. It is relevant every time a passphrase isasked, for example for open, luksFormat or luksAddKey. 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 defaultis a value of 0 seconds, which means to wait forever.


                            cryptsetup --timeout ...

--tries

How often the input of the passphrase shall be retried. This option is relevant every time a passphrase is asked, for examplefor open, luksFormat or luksAddKey. The default is 3 tries.


                            cryptsetup --tries ...

--align-payload

Align payload at a boundary of value 512-byte sectors. This option is relevant for luksFormat.If not specified, cryptsetup tries to use the topology info provided by the kernel for the underlying device to get the opti‐mal alignment. If not available (or the calculated value is a multiple of the default) data is by default aligned to a 1MiBboundary (i.e. 2048 512-byte sectors).For a detached LUKS header, this option specifies the offset on the data device. See also the --header option.


                            cryptsetup --align-payload ...

--uuid

Use the provided UUID for the luksFormat command instead of generating a new one. Changes the existing UUID when used with theluksUUID command.The UUID must be provided in the standard UUID format, e.g. 12345678-1234-1234-1234-123456789abc.


                            cryptsetup --uuid ...

--allow-discards

Allow the use of discard (TRIM) requests for the device. This option is only relevant for open action.WARNING: This command can have a negative security impact because it can make filesystem-level operations visible on the phys‐ical device. For example, information leaking filesystem type, used space, etc. may be extractable from the physical device ifthe 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.


                            cryptsetup --allow-discards ...

--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 encryptionwork is automatically balanced between available CPUs. This option is only relevant for open action.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.


                            cryptsetup --perf-same_cpu_crypt ...

--perf-submit_from_crypt_cpus

Disable offloading writes to a separate thread after encryption. There are some situations where offloading write bios fromthe encryption threads to a single thread degrades performance significantly. The default is to offload write bios to thesame thread. This option is only relevant for open action.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.


                            cryptsetup --perf-submit_from_crypt_cpus ...

--test-passphrase

Do not activate the device, just verify passphrase. This option is only relevant for open action (the device mapping name isnot mandatory if this option is used).


                            cryptsetup --test-passphrase ...

--header

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertextand LUKS header on different devices.This option is only relevant for LUKS devices and can be used with the luksFormat, open, luksSuspend, luksResume, status andresize commands.For luksFormat with a file name as the argument to --header, the file will be automatically created if it does not exist. Seethe cryptsetup FAQ for header size calculation.For other commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly asthe LUKS device.If used with luksFormat, the --align-payload option is taken as absolute sector alignment on ciphertext device and can bezero.WARNING: There is no check whether the ciphertext device specified actually belongs to the header given. In fact, you canspecify an arbitrary device as the ciphertext device for open with the --header option. Use with care.


                            cryptsetup --header ...

--header-backup-file

Specify file with header backup for luksHeaderBackup or luksHeaderBackup actions.


                            cryptsetup --header-backup-file ...

--force-password

Do not use password quality checking for new LUKS passwords.This option applies only to luksFormat, luksAddKey and luksChangeKey and is ignored if cryptsetup is built without passwordquality checking support.For more info about password quality check, see the manual page for pwquality.conf(5) and passwdqc.conf(5).


                            cryptsetup --force-password ...

--deferred

Defers device removal in close command until the last user closes it.


                            cryptsetup --deferred ...

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


                            cryptsetup --disable-locks ...

--disable-keyring

Do not load volume key in kernel keyring but use store key directly in the dm-crypt target. This option is supported only forthe LUKS2 format.


                            cryptsetup --disable-keyring ...

--key-description

Set key description in keyring for use with token command.


                            cryptsetup --key-description ...

--priority

Set a priority for LUKS2 keyslot. The prefer priority marked slots are tried before normal priority. The ignored prioritymeans, that slot is never used, if not explicitly requested by --key-slot option.


                            cryptsetup --priority ...

--token-id

Specify what token to use in actions token, open or resize. If omitted, all available tokens will be checked before proceed‐ing further with passphrase prompt.


                            cryptsetup --token-id ...

--token-only

Do not proceed further with action (any of token, open or resize) if token activation failed. Without the option, action asksfor passphrase to proceed further.


                            cryptsetup --token-only ...

--sector-size

Set sector size for use with disk encryption. It must be power of two and in range 512 - 4096 bytes. The default is 512 bytessectors. This option is available only in the LUKS2 mode.Note that if sector size is higher than underlying device hardware sector and there is not integrity protection that uses datajournal, using this option can increase risk on incomplete sector writes during a power fail.If used together with --integrity option and dm-integrity journal, the atomicity of writes is guaranteed in all cases (but itcost write performance - data has to be written twice).Increasing sector size from 512 bytes to 4096 bytes can provide better performance on most of the modern storage devices andalso with some hw encryption accelerators.


                            cryptsetup --sector-size ...

--persistent

If used with LUKS2 devices and activation commands like open, the specified activation flags are persistently written intometadata and used next time automatically even for normal activation. (No need to use cryptab or other system configurationfiles.) Only --allow-discards, --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus and --integrity-no-journal can be storedpersistently.


                            cryptsetup --persistent ...

--integrity

Specify integrity algorithm to be used for authenticated disk encryption in LUKS2.WARNING: This extension is EXPERIMENTAL and requires dm-integrity kernel target (available since kernel version 4.12). Formore info, see AUTHENTICATED DISK ENCRYPTION section.


                            cryptsetup --integrity ...

--integrity-no-journal

Activate device with integrity protection without using data journal (direct write of data and integrity tags). Note thatwithout journal power fail can cause non-atomic write and data corruption. Use only if journalling is performed on a differ‐ent storage layer.


                            cryptsetup --integrity-no-journal ...

--integrity-no-wipe

Skip wiping of device authentication (integrity) tags. If you skip this step, sectors will report invalid integrity tag untilan application write to the sector.NOTE: Even some writes to the device can fail if the write is not aligned to page size and page-cache initiates read of a sec‐tor with invalid integrity tag.


                            cryptsetup --integrity-no-wipe ...

--veracrypt

Allow VeraCrypt compatible mode. Only for TCRYPT extension. See TCRYPT section for more info.


                            cryptsetup --veracrypt ...

--version

Show the program version.


                            cryptsetup --version ...

--usage

Show short option help.


                            cryptsetup --usage ...

--help

Show help text and default parameters.RETURN CODESCryptsetup returns 0 on success and a non-zero value on error.Error codes are: 1 wrong parameters, 2 no permission (bad passphrase), 3 out of memory, 4 wrong device specified, 5 device alreadyexists or device is busy.NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODENote that no iterated hashing or salting is done in plain mode. If hashing is done, it is a single direct hash. This means that low-entropy passphrases are easy to attack in plain mode.From a terminal: The passphrase is read until the first newline, i.e. '\n'. The input without the newline character is processedwith the default hash or the hash specified with --hash. The hash result will be truncated to the key size of the used cipher, orthe size specified with -s.From stdin: Reading will continue until a newline (or until the maximum input size is reached), with the trailing newline stripped.The maximum input size is defined by the same compiled-in default as for the maximum key file size and can be overwritten using


                            cryptsetup --help ...