cryptsetup-open

title: cryptsetup-open(8)

text:
# cryptsetup-open(8)

## 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 <device_type> [<options>] <device> <name>

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

### PLAIN
open --type plain <device> <name> --cipher <spec> --key-size <bits> --hash <alg>

plainOpen <device> <name> (old syntax)

create <name> <device> (OBSOLETE syntax)

Opens (creates a mapping with) <name> backed by device <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.

<options> 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 <device> <name>

open --type <luks1|luks2> <device> <name> (explicit version request)

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

<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, --volume-key-keyring, --link-vk-to-keyring, --external-tokens-path].

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

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

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

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

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

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

### BitLocker
open --type bitlk <device> <name>

bitlkOpen <device> <name> (old syntax)

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

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.

<options> 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 <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
--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 <cipher-spec>

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 <absolute 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 <hash-spec>

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 <device or file storing the LUKS 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 <keyring description>::<key description>

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

<key description> part describes key type and key name of volume key linked in the keyring described in <keyring description>. The type may be specified by adding a "%<type_name>:" 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 <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.

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

Set the size of the device in sectors of 512 bytes. Usable only with plain device type.

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

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 <key description> uses keyctl-compatible syntax. This can either be a numeric key ID or a string name in the format %<key type>:<key name>. See also the KEY IDENTIFIERS section of keyctl(1). When no %<key type>: prefix is specified, we assume the key type is user (default type).

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

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

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

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

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-reencrypt

package: cryptsetup

title: cryptsetup-reencrypt(8)

summary: reencrypt LUKS encrypted volumes in\-place

text:
# cryptsetup-reencrypt(8)

## NAME
cryptsetup-reencrypt - reencrypt LUKS encrypted volumes in-place

## SYNOPSIS
cryptsetup reencrypt [<options>] <device> or --active-name <name> [<new_name>]

## DESCRIPTION
Run LUKS device reencryption.

There are 3 basic modes of operation:

•device reencryption (reencrypt)

•device encryption (reencrypt --encrypt/--new/-N)

•device decryption (reencrypt --decrypt)

<device> or --active-name <name> (LUKS2 only) is mandatory parameter.

Cryptsetup reencrypt action can be used to change reencryption parameters, which otherwise require full on-disk data change (re-encryption). The reencrypt action reencrypts data on the LUKS device in-place.

You can regenerate volume key (the real key used in on-disk encryption unlocked by passphrase), cipher, cipher mode or encryption sector size (LUKS2 only).

If you need to use both luksChangeKey and reencrypt (e.g., to recover from a leak), you need to use them in that order to avoid leaking the new volume key.

The reencryption process may be safely interrupted by a user via SIGINT signal (ctrl+c). The same applies to the SIGTERM signal (i.e., issued by systemd during system shutdown).

For in-place encryption mode, the reencrypt action additionally takes all options available for the luksFormat action for the respective LUKS version (see cryptsetup-luksFormat man page for more details). See cryptsetup-luksFormat(8).

Note that for encrypt and decrypt mode, the whole device must be treated as unencrypted — there are no guarantees of confidentiality as part of the device contains plaintext.

ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS ACTION ON LUKS DEVICE.

<options> can be [--batch-mode, --block-size, --cipher, --debug, --debug-json, --decrypt, --device-size, --disable-locks, --encrypt, --force-offline-reencrypt, --hash, --header, --hotzone-size, --iter-time, --init-only, --keep-key, --key-file, --key-size, --key-slot, --keyfile-offset, --keyfile-size, --tries, --timeout, --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --progress-frequency, --progress-json, --reduce-device-size, --resilience, --resilience-hash, --resume-only, --sector-size, --use-directio, --use-random, --use-urandom, --use-fsync, --uuid, --verbose, --volume-key-file, --write-log].

## LUKS2 REENCRYPTION
With the <device> parameter, cryptsetup looks up the active <device> dm mapping. If no active mapping is detected, it starts offline LUKS2 reencryption; otherwise, online reencryption occurs.

To resume already initialized or interrupted reencryption, just run the cryptsetup reencrypt command again to continue the reencryption operation. Reencryption may be resumed with different --resilience or --hotzone-size unless implicit datashift resilience mode is used: either encrypt mode with --reduce-device-size option or decrypt mode with original LUKS2 header exported in --header file.

If the reencryption process was interrupted abruptly (reencryption process crash, system crash, or power off), it may require recovery. The recovery is run automatically on next activation (action open) when needed or explicitly by the user (action repair).

The optional parameter <new_name> takes effect only with the encrypt option, and it activates device <new_name> immediately after encryption initialization is finished. That’s useful when the device needs to be ready as soon as possible and mounted (used) before full data area encryption is completed.

## LUKS1 REENCRYPTION
The current working directory must be writable, and temporary files created during reencryption must be present. During reencryption, the LUKS1 device is marked unavailable and must be offline (no dm-crypt mapping or mounted filesystem).

WARNING: The LUKS1 reencryption code is not resistant to hardware or kernel failures during reencryption (you can lose your data in this case).

## OPTIONS
--align-payload <number of 512 byte sectors> (DEPRECATED, use --offset)

Align payload at a boundary of value 512-byte sectors. If not specified, cryptsetup tries to use the topology info provided by the kernel for the underlying device to get the optimal alignment. If not available (or the calculated value is a multiple of the default), data is by default aligned to a 1MiB boundary (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.

This option is DEPRECATED and has an unexpected impact on the data offset and keyslot area size (for LUKS2) due to the complex rounding. For fixed data device offset, use --offset option instead.

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

--block-size value (LUKS1 only)

Use re-encryption block size of value in MiB. Values can be between 1 and 64 MiB.

--cipher, -c <cipher-spec>

LUKS2: Set the cipher specification string for the data segment only. LUKS1: Set the cipher specification string for the data segment and keyslots.

The default cipher is applied if the cipher specification is omitted in encrypt mode.

In reencrypt mode, if no new cipher specification is requested, the existing cipher will remain. The only exception is if the cipher is "cipher_null", then the default cipher is used.

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.

--decrypt

Initialize (and run) device decryption mode.

--device-size size[units]

Instead of the real device size, use the specified value. It means that only the specified area (from the start of the device to the specified size) will be reencrypted. LUKS2: When used together with --reduce-device-size, only the initial size value (--device-size parameter) of data is shifted backwards while being encrypted.

The sum of --device-size and --reduce-device-size values must not exceed the real device size.

WARNING: This is a destructive operation. Data beyond --device-size limit may be lost after the operation is finished.

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

Disable use of the blkid library for checking and wiping on-disk signatures.

--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. With locking disabled, LUKS2 images in files can be fully (re)encrypted offline without the need for superuser privileges provided that the used block ciphers are available in the crypto backend.

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

--encrypt, --new, -N

Initialize (and run) the device in-place encryption mode.

--force-no-keyslots (LUKS2 only)

Enforce initialization of reencryption operation with additional --volume-key-file, --new-volume-key-file, --volume-key-keyring or --new-volume-key-keyring parameters. It would result in the deletion of all remaining LUKS2 keyslots containing the volume key. LUKS2 keyslot with the new volume key may be added after the reencryption operation is finished. See cryptsetup-luksAddKey(8) command.

WARNING: Use with extreme caution! If you lose the volume key stored in a file or in a kernel keyring before adding the LUKS2 keyslot containing the new volume key, the device will become unusable, and all data will be lost.

--force-offline-reencrypt (LUKS2 only)

Bypass active device auto-detection and enforce offline reencryption. This option is useful especially for reencryption of LUKS2 images put in files (auto-detection is not reliable in this scenario).

It may also help in case active device auto-detection on a particular data device does not work or report errors.

WARNING: Use with extreme caution! This may destroy data if the device is activated and/or actively used.

--force-password

Do not use password quality checking for new LUKS passwords. This option is ignored if cryptsetup is built without password quality checking support.

For more info about password quality check, see the manual page for pwquality.conf(5) and passwdqc.conf(5).

--hash, -h <hash-spec>

LUKS1: Specifies the hash used in the LUKS1 key setup scheme and volume key digest. If this parameter is not specified, the default hash algorithm is always used for a new LUKS1 device header.

LUKS2: Ignored unless new keyslot pbkdf algorithm is set to PBKDF2 (see --pbkdf).

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. If used with --encrypt/--new option, the header file will be created (or overwritten). Use with care.

LUKS2: For decryption mode, the option may be used to export the original LUKS2 header to a detached file. The passed future file must not exist at the time of initializing the decryption operation. This frees space in the head of the data device so that data can be moved at the original LUKS2 header location. Later on, the decryption operation continues as if the ordinary detached header was passed.

WARNING: Never put an exported header file in a filesystem on top of the device you are about to decrypt! It would cause a deadlock.

--help, -?

Show help text and default parameters.

--hotzone-size size (LUKS2 only)

This option can be used to set an upper limit on the size of the reencryption area (hotzone). The size can be specified with a unit suffix (for example, 50M). Note that the actual hotzone size may be less than specified <size> due to other limitations (free space in keyslots area or available memory). With decryption mode for devices with LUKS2 header placed in the head of the data device, the option specifies how large is the first data segment moved from the original data offset pointer.

--init-only (LUKS2 only)

Initialize reencryption (any mode) operation in LUKS2 metadata only and exit. If any reencrypt operation is already initialized in metadata, the command with --init-only parameter fails.

--iter-time, -i <number of milliseconds>

The number of milliseconds to spend with PBKDF passphrase processing for the new LUKS header.

--keep-key

LUKS2: Do not change the effective volume key, and change other parameters if requested. LUKS1: Reencrypt only the LUKS1 header and keyslots. Skips data in-place reencryption.

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

The --key-file option can be used only if there is only one active keyslot, or alternatively, also if --key-slot option is specified (then all other keyslots will be disabled in the new LUKS device).

If this option is not used, cryptsetup will ask for all active keyslot passphrases.

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

LUKS2: Provide current key size in bits. The argument has to be a multiple of 8. Useful when specifying the size of the current volume key when no keyslot is active. LUKS1: See --new-key-size.

--key-slot, -S <0-N>

For LUKS operations that add key material, this option allows you to specify which keyslot is selected for the new key. For reencryption mode, it selects a specific keyslot (and passphrase) that can be used to unlock the new volume key. If used, all other keyslots get removed after the reencryption operation is finished.

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.

--keyslot-cipher <cipher-spec>

This option can be used to set specific cipher encryption for the LUKS2 keyslot area.

--keyslot-key-size <bits>

This option can be used to set a specific key size for the LUKS2 keyslot area.

--label <label>, --subsystem <subsystem>

Set label and subsystem description for LUKS2 device. These are similar to filesystem labels. The label and subsystem are optional fields and can be later used in udev scripts to trigger user actions once the device marked by these labels is detected.

--luks2-keyslots-size size

This option can be used to set a specific size of the LUKS2 binary keyslot area (key material is encrypted there). The value must be aligned to a multiple of 4096 bytes with a maximum size 128MB. The <size> can be specified with a unit suffix (for example, 128k).

--luks2-metadata-size size

This option can be used to enlarge the LUKS2 metadata (JSON) area. The size includes 4096 bytes for binary metadata (usable JSON area is smaller of the binary area). According to the LUKS2 specification, only these values are valid: 16, 32, 64, 128, 256, 512, 1024, 2048 and 4096 kB. The <size> can be specified with a unit suffix (for example, 128k).

--new-key-size bits

Sets new key size in bits. The argument has to be a multiple of 8. The possible key sizes are limited by the new cipher and mode used in reencryption. See /proc/crypto for more information. Note that the key size in /proc/crypto is stated in bytes.

LUKS1: If you are increasing key size, there must be enough space in the LUKS header for enlarged keyslots (data offset must be large enough), or reencryption cannot be performed.

If there is not enough space for keyslots with the new key size, you can destructively shrink the device with --reduce-device-size option.

--new-volume-key-file file

Use (set) the new volume key stored in a file. The option must be paired with --new-key-size parameter when initializing the reencryption operation. WARNING: If you create your own volume key, you need to make sure to do it right. Otherwise, you can end up with a low-entropy or otherwise partially predictable volume key, which will compromise security.

--new-volume-key-keyring <key description>

Use (set) the new volume key stored in a keyring. The size of the key stored in a keyring must be compatible with the new cipher used in the reencryption operation. See /proc/crypto for more information. Note that the key size in /proc/crypto is stated in bytes.

The <key description> uses keyctl-compatible syntax. This can either be a numeric key ID or a string name in the format %<key type>:<key name>. See also the KEY IDENTIFIERS section of keyctl(1). When no %<key type>: prefix is specified, we assume the key type is user (default type).

WARNING: If you create your own volume key, you need to make sure to do it right. Otherwise, you can end up with a low-entropy or otherwise partially predictable volume key, which will compromise security.

--offset, -o <number of 512 byte sectors>

Start offset in the backend device in 512-byte sectors. This option is only relevant for the encrypt mode. The --offset option sets the data offset (payload) of the data device and must be aligned to 4096-byte sectors (must be a multiple of 8). This option cannot be combined with --align-payload option.

--pbkdf <PBKDF spec>

Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot. The PBKDF can be: pbkdf2 (for PBKDF2 according to RFC2898), argon2i for Argon2i or argon2id for Argon2id (see Argon2 <https://www.cryptolux.org/index.php/Argon2> for more info). For LUKS1, only PBKDF2 is accepted (no need to use this option). The default PBKDF for LUKS2 is set during compilation time and is available in the cryptsetup --help output.

A PBKDF is used for increasing the dictionary and brute-force attack cost for keyslot passwords. The parameters can be time, memory and parallel cost.

For PBKDF2, only the time cost (number of iterations) applies. For Argon2i/id, there is also memory cost (memory required during the 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 benchmark tries to find iteration time (--iter-time) with required memory cost --pbkdf-memory. If it is not possible, the memory cost is decreased as well. The parallel cost --pbkdf-parallel is constant and is checked against available CPU cores.

You can see all PBKDF parameters for a particular LUKS2 keyslot with the cryptsetup-luksDump(8) command.

If you do not want to use benchmark and want to specify all parameters directly, use --pbkdf-force-iterations with --pbkdf-memory and --pbkdf-parallel. This will override the values without benchmarking. Note it can cause extremely long unlocking time or cause out-of-memory conditions with unconditional process termination. Use only in specific cases, for example, if you know that the formatted device will be used on some small embedded system.

MINIMAL AND MAXIMAL PBKDF COSTS: For PBKDF2, the minimum iteration count is 1000 and the maximum is 4294967295 (maximum for 32-bit unsigned integer). Memory and parallel costs are not supported for PBKDF2. For Argon2i and Argon2id, the minimum iteration count (CPU cost) is 4, and the maximum is 4294967295 (maximum for a 32-bit unsigned integer). Minimum memory cost is 32 KiB and maximum is 4 GiB. If the memory cost parameter is benchmarked (not specified by a parameter), it is always in the range from 64 MiB to 1 GiB. Memory cost above 1GiB (up to the 4GiB maximum) can be setup only by the --pbkdf-memory parameter. The parallel cost minimum is 1 and maximum 4 (if enough CPU cores are available, otherwise it is decreased by the available CPU cores).

WARNING: Increasing PBKDF computational costs above the mentioned limits provides negligible additional security improvement. While elevated costs significantly increase brute-force overhead, they offer negligible protection against dictionary attacks. The marginal cost increase for processing an entire dictionary remains fundamentally insufficient.

The hardcoded PBKDF limits represent engineered trade-offs between cryptographic security and operational usability. LUKS maintains portability and must be used within a reasonable time on resource-constrained systems.

Cryptsetup deliberately restricts maximum memory cost (4 GiB) and parallel cost (4) parameters due to architectural limitations (like embedded and legacy systems).

PBKDF memory cost mandates actual physical RAM allocation with intensive write operations that must remain in physical RAM. Any swap usage results in unacceptable performance degradation. Memory management often overcommits allocations beyond available physical memory, expecting most allocated memory to remain unused. In such situations, as PBKDF always uses all allocated memory, it frequently causes out-of-memory failures that abort cryptsetup operations.

--pbkdf-force-iterations number

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

--pbkdf-memory number

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

--pbkdf-parallel number

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

--progress-frequency seconds

Print a separate line every seconds with reencryption progress.

--progress-json

Prints progress data in JSON format, which is suitable mostly for machine processing. It prints a separate line every half second (or based on --progress-frequency value). The JSON output looks as follows during progress (except it’s a compact single line):

```
{

  "device":"/dev/sda",      // backing device or file

  "device_bytes":"8192",    // bytes of I/O so far

  "device_size":"44040192", // total bytes of I/O to go

  "speed":"126877696",      // calculated speed in bytes per second (based on progress so far)

  "eta_ms":"2520012",       // estimated time to finish an operation in milliseconds

  "time_ms":"5561235"       // total time spent in IO operation in milliseconds
}
```

Note on numbers in JSON output: Due to JSON parser limitations, all numbers are represented in a string format due to the need for full 64-bit unsigned integers.

--reduce-device-size size

This means that the last size sectors on the original device will be lost, and data will be effectively shifted by the specified number of sectors. It could be useful if you added some space to the underlying partition or logical volume (so the ast size sectors contains no data).

For units suffix, see --device-size parameter description.

WARNING: This is a destructive operation and cannot be reverted. Use with extreme care - accidentally overwritten filesystems are usually unrecoverable.

LUKS2: Initialize LUKS2 reencryption with data device size reduction (currently, only encryption mode is supported). The last size sectors on the original plaintext device is used for temporarily storing the original first data segment. The former first data segment is replaced with LUKS2 header (half the size value), and plaintext data is shifted backwards (again half the size value) while being encrypted.

The recommended minimum size is twice the default LUKS2 header size (--reduce-device-size 32M) for encryption mode.

The sum of --device-size and --reduce-device-size values must not exceed the real device size.

LUKS1: Enlarge the data offset to the specified value by shrinking the device size.

You cannot shrink the device by more than 64 MiB (131072 sectors).

--resilience mode (LUKS2 only)

Reencryption resilience mode can be one of checksum, journal or none. checksum: default mode, where individual checksums of ciphertext hotzone sectors are stored, so the recovery process can detect which sectors were already reencrypted. It requires that the device sector write is atomic.

journal: The hotzone is journaled in the binary area (so the data are written twice).

none: Performance mode. There is no protection, and the only way it’s safe to interrupt the reencryption is similar to an old offline reencryption utility.

Resilience modes can be changed unless datashift mode is used for operation initialization (encryption with --reduce-device-size option).

--resilience-hash hash (LUKS2 only)

The hash algorithm is used with "--resilience checksum" only. The default hash is sha256. With other resilience modes, the hash parameter is ignored.

--resume-only (LUKS2 only)

Resume reencryption (any mode) operation that is already described in LUKS2 metadata. If no reencrypt operation is initialized, the command with --resume-only parameter fails. Useful for resuming the reencrypt operation without accidentally triggering a new reencryption operation.

--sector-size bytes (LUKS2 only)

Reencrypt the device with a new encryption sector size enforced. WARNING: Increasing the encryption sector size may break the hosted filesystem. Do not run reencryption with --force-offline-reencrypt if unsure what block size the filesystem was formatted with.

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.

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

LUKS2 reencryption initialization: Specify what keyslots (associated with the selected token) to use for LUKS2 reencryption. If the reencryption operation changes the effective volume key, only keyslots associated with the token and unlocked successfully will be available after the reencryption operation is finished. LUKS2 reencryption resume: 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

LUKS2 reencryption initialization: Specify that all keyslots associated with any token will be used for LUKS2 reencryption. If the reencryption operation changes the effective volume key, only keyslots associated with any token will be available after the reencryption operation is finished. LUKS2 reencryption resume: 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

LUKS2 reencryption initialization: Specify what keyslots (associated with the selected token type) to use for LUKS2 reencryption. If the reencryption operation changes the effective volume key, only keyslots associated with the token type and unlocked successfully will be available after the reencryption operation is finished. LUKS2 reencryption resume: 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 (encryption mode) or expected (other modes) LUKS format. Accepts only luks1 or luks2.

--usage

Show short option help.

--use-directio (LUKS1 only)

Use direct-io (O_DIRECT) for all read/write data operations related to the block device undergoing reencryption. Useful if direct-io operations perform better than normal buffered operations (e.g., in virtual environments).

--use-fsync (LUKS1 only)

Use the fsync call after every written block. This applies to reencryption log files as well.

--use-random, --use-urandom

Define which kernel random number generator will be used to create the volume key.

--uuid UUID

When used in encryption mode, use the provided UUID for the new LUKS header instead of generating a new one. LUKS1 (only in decryption mode): To find out what UUID to pass, look for temporary files LUKS-UUID.[|log|org|new] of the interrupted decryption process.

The UUID must be provided in the standard UUID format, e.g., 12345678-1234-1234-1234-123456789abc.

--verify-passphrase, -y

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Ignored on input from file or stdin.

--version, -V

Show the program version.

--volume-key-file file, --master-key-file file (OBSOLETE alias)

LUKS2: Provides the current volume key stored in a file. It can be used to reencrypt the device with no active keyslot together with --new-volume-key-file or --new-volume-key-keyring options. LUKS1: See --new-volume-key-file.

--write-log (LUKS1 only)

Update the log file after every block is written. This can slow down reencryption, but it will minimize data loss in the case of a system crash.

## EXAMPLES
You may drop --type luks2 option as long as LUKS2 format is default.

### LUKS2 ENCRYPTION EXAMPLES
Encrypt LUKS2 device (in-place). Make sure the last 32 MiB on /dev/plaintext is unused (e.g., does not contain filesystem data):

cryptsetup reencrypt --encrypt --type luks2 --reduce-device-size 32m /dev/plaintext_device

Encrypt LUKS2 device (in-place). Only the initial 1 GiB of original /dev/plaintext data is encrypted while being shifted backwards. Make sure the last 32 MiB (tail) on the data device is unused (e.g., does not contain any data):

cryptsetup reencrypt --encrypt --type luks2 --device-size 1g --reduce-device-size 32m /dev/plaintext_device

Encrypt LUKS2 device (in-place) with detached header, put in a file:

cryptsetup reencrypt --encrypt --type luks2 --header my_luks2_header /dev/plaintext_device

Initialize LUKS2 in-place encryption operation only and activate the device (not yet encrypted):

cryptsetup reencrypt --encrypt --type luks2 --init-only --reduce-device-size 32m /dev/plaintext_device my_future_luks_device

Resume online encryption on the device initialized in the example above:

cryptsetup reencrypt --resume-only /dev/plaintext_device or cryptsetup reencrypt --active-name my_future_luks_device

### LUKS2 REENCRYPTION EXAMPLES
Reencrypt LUKS2 device (refresh volume key only):

cryptsetup reencrypt /dev/encrypted_device

Reencrypt LUKS2 device using keyslot(s) associated with the token 3. All other keyslots will be removed after the reencryption finishes.

cryptsetup reencrypt --token-id 3 /dev/encrypted_device

Reencrypt LUKS2 device using keyslots associated with all 'systemd-tpm2' tokens. All other keyslots will be removed after the reencryption finishes.

cryptsetup reencrypt --token-type systemd-tpm2 /dev/encrypted_device

### LUKS2 DECRYPTION EXAMPLES
Decrypt LUKS2 device with header put in the head of the data device (header file does not exist):

cryptsetup reencrypt --decrypt --header /export/header/to/file /dev/encrypted_device

Decrypt LUKS2 device with detached header (header file exists):

cryptsetup reencrypt --decrypt --header detached-luks2-header /dev/encrypted_device

Resume interrupted LUKS2 decryption:

cryptsetup reencrypt --resume-only --header luks2-hdr-file /dev/encrypted_device

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

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

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

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

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.

branch: sisyphus


cryptsetup-refresh

title: cryptsetup-refresh(8)

summary: refresh parameters of an active mapping

text:
# cryptsetup-refresh(8)

## NAME
cryptsetup-refresh - refresh parameters of an active mapping

## SYNOPSIS
cryptsetup refresh [<options>] <name>

## DESCRIPTION
Refreshes parameters of active mapping <name>.

Update parameters of active device <name> without the need to deactivate the device (and unmount the filesystem). Currently, it supports parameter refresh on the following devices: LUKS1, LUKS2 (including authenticated encryption), plain crypt and loop-AES.

Mandatory parameters are identical to those of an open action for the respective device type.

You may change the following parameters on all devices --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue and --allow-discards.

Refreshing the device without any optional parameter will refresh the device with the default setting (respective to device type).

LUKS2 only:

The --integrity-no-journal parameter affects only LUKS2 devices with the underlying dm-integrity device.

Adding option --persistent stores any combination of device parameters above in LUKS2 metadata (only after successful refresh operation).

The --disable-keyring parameter refreshes a device with the volume key passed in the dm-crypt driver.

<options> can be [--allow-discards, --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue, --header, --disable-keyring, --disable-locks, --persistent, --integrity-no-journal].

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

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

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

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--help, -?

Show help text and default parameters.

--integrity-no-journal

Activate device with integrity protection without using data journal (direct write of data and integrity tags). Note that without a journal, a power failure can cause non-atomic writes and data corruption. Use only if journaling is performed on a different storage layer.

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

--usage

Show short option help.

--version, -V

Show the program version.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

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

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

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

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-repair

title: cryptsetup-repair(8)

summary: repair the device metadata

text:
# cryptsetup-repair(8)

## NAME
cryptsetup-repair - repair the device metadata

## SYNOPSIS
cryptsetup repair [<options>] <device>

## DESCRIPTION
Tries to repair the device metadata if possible. Currently supported only for LUKS device type.

This command is useful for fixing some known benign LUKS metadata header corruptions. Only basic corruptions of unused keyslot are fixable. This command will only change the LUKS header, not any keyslot data. You may enforce LUKS version by adding --type option.

It also repairs (upgrades) LUKS2 reencryption metadata by adding a metadata digest that protects it against malicious changes.

If LUKS2 reencryption was interrupted while writing the reencryption segment, the repair command can perform reencryption recovery so that reencryption can continue later. Repairing reencryption requires verification of the reencryption keyslot, so a passphrase or keyfile is needed.

WARNING: Always create a binary backup of the original header before calling this command.

### LUKS keyslots corruption detection
The repair command also checks for detectable corruption of keyslot content. Corruption of a keyslot results in a situation where a known password is no longer accepted. It can happen due to storage media failure or overwriting the keyslot area with other data. Only certain corruptions, usually only a low-entropy area (like zeroed blocks), can be detected.

The detection prints only warnings. It does not modify keyslots. It can also print more specific offsets on the device for detailed manual inspection.

Please note that the warning can be a false positive (no real corruption happened). Conversely, if the keyslot is corrupted, no recovery is possible. You have to use the LUKS header backup.

<options> can be [--timeout, --verify-passphrase, --disable-locks, --type, --header, --key-file, --keyfile-size, --keyfile-offset, --key-slot].

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

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

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--help, -?

Show help text and default parameters.

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

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-slot, -S <0-N>

For LUKS operations that add key material, this option allows you to specify which keyslot is selected for the new key. 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.

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

--type type

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

--usage

Show short option help.

--verify-passphrase, -y

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Ignored on input from file or stdin.

--version, -V

Show the program version.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

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

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

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

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-resize

title: cryptsetup-resize(8)

summary: resize an active mapping

text:
# cryptsetup-resize(8)

## NAME
cryptsetup-resize - resize an active mapping

## SYNOPSIS
cryptsetup resize [<options>] <name>

## DESCRIPTION
Resizes an active mapping <name>.

If --size (in 512-byte sectors) or --device-size is not specified, the size is computed from the underlying device. For LUKS, it is the size of the underlying device without the area reserved for the LUKS header (see data payload offset in the luksDump command). For a plain crypt device, the whole device size is used.

Note that this does not change the raw device geometry; it just changes how many sectors of the raw device are represented in the mapped device.

If cryptsetup detected a volume key for the active device loaded in the kernel keyring service, the resize action would first try to retrieve the key using a token. Only if it failed, it’d ask for a passphrase to unlock a keyslot (LUKS) or to derive a volume key again (plain mode). The kernel keyring is used by default for LUKS2 devices.

<options> can be [--size, --device-size, --token-id, --token-only, --token-type, --key-slot, --key-file, --keyfile-size, --keyfile-offset, --timeout, --disable-external-tokens, --disable-locks, --disable-keyring, --volume-key-keyring, --verify-passphrase, --timeout, --external-tokens-path].

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

--device-size size[units]

Sets the new size of the device. If unset, the real device size is used. 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).

--external-tokens-path <absolute 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).

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--help, -?

Show help text and default parameters.

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

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-slot, -S <0-N>

For LUKS operations that add key material, this option allows you to specify which keyslot is selected for the new key. 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.

--size, -b <number of 512 byte sectors>

Set the size of the device in sectors of 512 bytes.

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

--usage

Show short option help.

--verify-passphrase, -y

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Ignored on input from file or stdin.

--version, -V

Show the program version.

--volume-key-keyring <key description>

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 <key description> uses keyctl-compatible syntax. This can either be a numeric key ID or a string name in the format %<key type>:<key name>. See also the KEY IDENTIFIERS section of keyctl(1). When no %<key type>: prefix is specified, we assume the key type is user (default type).

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

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

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

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

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-status

title: cryptsetup-status(8)

summary: report the status for a mapping

text:
# cryptsetup-status(8)

## NAME
cryptsetup-status - report the status for a mapping

## SYNOPSIS
cryptsetup status [<options>] <name>

## DESCRIPTION
Reports the status for the mapping <name>.

<options> can be [--header, --disable-locks].

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

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

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--help, -?

Show help text and default parameters.

--usage

Show short option help.

--version, -V

Show the program version.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

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

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

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

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-tcryptDump

title: cryptsetup-tcryptDump(8)

text:
# cryptsetup-tcryptDump(8)

## NAME
cryptsetup-tcryptDump - dump the header information of a TCRYPT (TrueCrypt or VeraCrypt compatible) device

## SYNOPSIS
cryptsetup tcryptDump [<options>] <device>

## DESCRIPTION
Dump the header information of a TCRYPT (TrueCrypt or VeraCrypt compatible) device.

If the --dump-volume-key option is used, the TCRYPT device volume key is dumped instead of the TCRYPT header info. Beware that the volume key (or concatenated volume keys if a cipher chain is used) can be used to decrypt the data stored in the TCRYPT container without a passphrase. This means that if the volume key is compromised, the whole device has to be erased to prevent further access. Use this option carefully.

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.

<options> can be [--dump-volume-key, --key-file, --tcrypt-hidden, --tcrypt-system, --tcrypt-backup, --veracrypt (ignored), --disable-veracrypt, --veracrypt-pim, --veracrypt-query-pim, --cipher, --hash, --header, --verify-passphrase, --timeout].

## OPTIONS
--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 <cipher-spec>

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.

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

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

--dump-volume-key, --dump-master-key (OBSOLETE alias)

Print the volume key in the displayed information. Use with care, as the volume key can be used to bypass the passphrases, see also option --volume-key-file.

--hash, -h <hash-spec>

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 <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--help, -?

Show help text and default parameters.

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

See section NOTES ON PASSPHRASE PROCESSING in cryptsetup(8) for more information.

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

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

--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. Ignored on input from file or stdin.

--version, -V

Show the program version.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

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

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

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

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-token

title: cryptsetup-token(8)

summary: manage LUKS2 tokens

text:
# cryptsetup-token(8)

## NAME
cryptsetup-token - manage LUKS2 tokens

## SYNOPSIS
cryptsetup token <add|remove|import|export|unassign> [<options>] <device>

## DESCRIPTION
Action add creates a new keyring token to enable auto-activation of the device. For the auto-activation, the passphrase must be stored in the keyring with the specified description. Usually, the passphrase should be stored in the user or user-session keyring. The token command is supported only for LUKS2.

For adding a new keyring token, the option --key-description is mandatory. Also, a new token is assigned to the keyslot specified with --key-slot option or to all active keyslots if the --key-slot option is omitted.

To remove an existing token, specify the token ID that should be removed with --token-id option.

WARNING: The action token remove removes any token type, not just keyring type from token slot specified by --token-id option.

Action import can store an arbitrary valid JSON data in the LUKS2 token. It may be passed via standard input or a file passed in --json-file option. If you specify --key-slot, a successfully imported token is also assigned to the keyslot.

Action export writes requested token JSON to a file passed with --json-file or to standard output.

Action unassign removes token binding to specified keyslot. Both token and keyslot must be specified by --token-id and --key-slot parameters.

If --token-id is used with action add or action import and a token with that ID already exists, option --token-replace can replace the existing token.

<options> can be [--header, --token-id, --key-slot, --key-description, --disable-external-tokens, --disable-locks, --disable-keyring, --json-file, --token-replace, --unbound, --external tokens-path].

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

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

--external-tokens-path <absolute 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).

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--help, -?

Show help text and default parameters.

--json-file

Read the token JSON from a file or write the token to it. Option --json-file=- reads JSON from standard input or writes it to standard output, respectively.

--key-description text

Set the key description in the keyring that will be used for passphrase retrieval.

--key-slot, -S <0-N>

For LUKS operations that add key material, this option allows you to specify which keyslot is selected for the new key. 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.

--token-id

Specify the token number. If omitted, the first unused token id is used when adding or importing a new token.

--token-replace

Replace an existing token when adding or importing a token with the --token-id option.

--unbound

Creates a new LUKS2 keyring token assigned to no keyslot. Usable only with the add action.

--usage

Show short option help.

--version, -V

Show the program version.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

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

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

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

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.