--verbose, -v
Print more information on command execution.
--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.
--type <device-type>
Specifies required device type, for more info read BASIC
ACTIONS section.
--hash, -h <hash-spec>
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. For luksFormat, the hash algorithm must provide
at least 160 bits of output, which excludes, e.g., MD5. Do
not use a non-crypto hash 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.
--cipher, -c <cipher-spec>
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 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.
XTS mode requires kernel 2.6.24 or later and plain64
requires kernel 2.6.33 or later. More information can be
found in the FAQ.
--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 regular mapping for the first time, or
when running luksFormat. Ignored on input from file or
stdin.
--key-file, -d name
Read the passphrase from file.
If the name given is "-", then the passphrase will be read
from stdin. In this case, reading will not stop at
newline characters.
With LUKS, passphrases supplied via --key-file are always
the existing passphrases requested by a command, except in
the case of 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.
--keyfile-offset value
Skip value bytes at the beginning of the key file. Works
with all commands that accept key files.
--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. Works with all commands that
accept key files.
--new-keyfile-offset value
Skip value bytes at the start when adding a new passphrase
from key file with luksAddKey.
--new-keyfile-size value
Read a maximum of value bytes when adding a new passphrase
from key file with luksAddKey. The default is to read the
whole file up to the compiled-in maximum length that can
be queried with --help. Supplying more than the compiled
in maximum aborts the operation. When
--new-keyfile-offset is also given, reading starts after
the offset.
--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 existing LUKS header and all other parameters are the
same, then the new header decrypts the data encrypted with
the header the master key was taken from.
Action luksDump together with --dump-master-key option:
The volume (master) key is stored in a file instead of
being printed out to standard output.
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-entropy or 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.
--dump-json-metadata
For luksDump (LUKS2 only) this option prints content of
LUKS2 header JSON metadata area.
--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 to bypass the passphrases, see also option
--master-key-file.
--json-file
Read token json from a file or write token to it. See
token action for more information. --json-file=- reads
json from standard input or writes it to standard output
respectively.
--use-random
--use-urandom
For luksFormat these options define which kernel random
number generator will be used to create the master key
(which is a long-term key).
See NOTES ON RANDOM NUMBER GENERATORS for more
information. Use cryptsetup --help to show the compiled-in
default random number generator.
WARNING: In a low-entropy situation (e.g. in an embedded
system), both selections are problematic. Using
/dev/urandom can lead to weak keys. Using /dev/random can
block a long time, potentially forever, if not enough
entropy can be harvested by the kernel.
--key-slot, -S <0-N>
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
passphrase would only match a different key-slot, the
operation fails.
Maximum number of key slots depends on LUKS version. LUKS1
can have up to 8 key slots. LUKS2 can have up to 32 key
slots based on key slot area size and key size, but a
valid key slot ID can always be between 0 and 31 for
LUKS2.
--key-size, -s <bits>
Sets key size in bits. The argument has to be a multiple
of 8. The possible key-sizes are limited by the cipher and
mode used.
See /proc/crypto for more information. Note that key-size
in /proc/crypto is stated in bytes.
This option can be used for open --type plain or
luksFormat. All other LUKS actions will use the key-size
specified in the LUKS header. Use cryptsetup --help to
show the compiled-in defaults.
--size, -b <number of 512 byte sectors>
Set the size of the device in sectors of 512 bytes. This
option is only relevant for the open and resize actions.
--offset, -o <number of 512 byte sectors>
Start offset in the backend device in 512-byte sectors.
This option is only relevant for the open action with
plain or loopaes device types or for LUKS devices in
luksFormat.
For LUKS, the --offset option sets the data offset
(payload) of data device and must be be aligned to
4096-byte sectors (must be multiple of 8). This option
cannot be combined with --align-payload option.
--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 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 the IV calculation.
--device-size size[units]
Instead of real device size, use specified value.
With reencrypt action it means that only specified area
(from the start of the device to the specified size) will
be reencrypted.
With resize action it sets new size of the device.
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).
WARNING: This is destructive operation when used with
reencrypt command.
--readonly, -r
set up a read-only mapping.
--shared
Creates an additional mapping for one common ciphertext
device. Arbitrary mappings are supported. This option is
only relevant for the open --type plain action. Use
--offset, --size and --skip to specify the mapped area.
--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
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 time and 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, memory and parallel cost.
For PBKDF2, only 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 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 --pbkdf-memory and
--pbkdf-parallel. This will override the values without
benchmarking. Note it can cause extremely long unlocking
time. 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 maximum is 4294967295 (maximum
for 32bit unsigned integer). Memory and parallel costs
are unused for PBKDF2. For Argon2i and Argon2id, minimum
iteration count (CPU cost) is 4 and maximum is 4294967295
(maximum for 32bit unsigned integer). Minimum memory cost
is 32 KiB and maximum is 4 GiB. (Limited by addresable
memory on some CPU platforms.) If the memory cost
parameter is benchmarked (not specified by a parameter) it
is always in range from 64 MiB to 1 GiB. The parallel
cost minimum is 1 and maximum 4 (if enough CPUs cores are
available, otherwise it is decreased).
--iter-time, -i <number of milliseconds>
The number of milliseconds to spend with PBKDF passphrase
processing. This option is only relevant for LUKS
operations that set or change passphrases, such as
luksFormat or luksAddKey. Specifying 0 as parameter
selects the compiled-in default.
--pbkdf-memory <number>
Set the memory cost for PBKDF (for Argon2i/id the number
represents kilobytes). Note that it is 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 maximal value, it is decreased
automatically if CPU online count is lower. This option
is not available for PBKDF2.
--pbkdf-force-iterations <num>
Avoid PBKDF benchmark and set time cost (iterations)
directly. It can be used for LUKS/LUKS2 device only. See
--pbkdf option for more info.
--batch-mode, -q
Suppresses all confirmation questions. Use with care!
If the -y option is not specified, this option also
switches off the passphrase verification for luksFormat.
--progress-frequency <seconds>
Print separate line every <seconds> with wipe progress.
--timeout, -t <number of seconds>
The number of seconds to wait before timeout on passphrase
input via terminal. It is relevant every time a passphrase
is asked, 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 default is a value of 0 seconds, which means to wait
forever.
--tries, -T
How often the input of the passphrase shall be retried.
This option is relevant every time a passphrase is asked,
for example for open, luksFormat or luksAddKey. The
default is 3 tries.
--align-payload <number of 512 byte sectors>
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 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.
WARNING: This option is DEPRECATED and has often
unexpected impact to the data offset and keyslot area size
(for LUKS2) due to the complex rounding. For fixed data
device offset use --offset option instead.
--uuid=UUID
Use the provided UUID for the luksFormat command instead
of generating a new one. Changes the existing UUID when
used with the luksUUID command.
The UUID must be provided in the standard UUID format,
e.g. 12345678-1234-1234-1234-123456789abc.
--allow-discards
Allow the use of discard (TRIM) requests for the device.
This option is only relevant for open action. This is
also not supported for LUKS2 devices with data integrity
protection.
WARNING: This command can have a negative security impact
because it can make filesystem-level operations visible on
the physical device. For example, information leaking
filesystem type, used space, etc. may be extractable from
the physical device if the discarded blocks can be located
later. If in doubt, do not use it.
A kernel version of 3.1 or later is needed. For earlier
kernels, this option is ignored.
--perf-same_cpu_crypt
Perform encryption using the same cpu that IO was
submitted on. The default is to use an unbound workqueue
so that encryption work is automatically balanced between
available CPUs. 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.
--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
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.
--perf-no_read_workqueue, --perf-no_write_workqueue
Bypass dm-crypt internal workqueue and process read or
write requests synchronously. This option is only
relevant for open action.
NOTE: These options are available only for low-level dm-
crypt performance tuning, use only if you need a change to
default dm-crypt behaviour. Needs kernel 5.9 or later.
--test-passphrase
Do not activate the device, just verify passphrase. This
option is only relevant for open action (the device
mapping name is not mandatory if this option is 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
ciphertext and LUKS header on different devices.
This option is only relevant for LUKS devices and can be
used with the luksFormat, open, luksSuspend, luksResume,
status and resize commands.
For luksFormat with a file name as the argument to
--header, the file will be automatically created if it
does not exist. See the 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 as the LUKS device.
If used with luksFormat, the --align-payload option is
taken as absolute sector alignment on ciphertext device
and can be zero.
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 for open with the --header option. Use with care.
--header-backup-file <file>
Specify file with header backup for luksHeaderBackup or
luksHeaderRestore actions.
--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 password quality checking support.
For more info about password quality check, see the manual
page for pwquality.conf(5) and passwdqc.conf(5).
--deferred
Defers device removal in close command until the last user
closes it.
--cancel-deferred
Removes a previously configured deferred device removal in
close command.
--disable-external-tokens
Disable loading of plugins for external LUKS2 tokens.
--disable-locks
Disable lock protection for metadata on disk. This option
is valid only for LUKS2 and ignored for other formats.
WARNING: Do not use this option unless you run cryptsetup
in a restricted environment where locking is impossible to
perform (where /run directory cannot be used).
--disable-keyring
Do not load volume key in kernel keyring and store it
directly in the dm-crypt target instead. This option is
supported only for the LUKS2 format.
--key-description <text>
Set key description in keyring for use with token command.
--priority <normal|prefer|ignore>
Set a priority for LUKS2 keyslot. The prefer priority
marked slots are tried before normal priority. The
ignored priority means, that slot is never used, if not
explicitly requested by --key-slot option.
--token-id
Specify what token to use in actions token, open or
resize. If omitted, all available tokens will be checked
before proceeding further with passphrase prompt.
--token-only
Do not proceed further with action (any of token, open or
resize) if token activation failed. Without the option,
action asks for passphrase to proceed further.
--token-type
Restrict tokens eligible for operation to specific token
type (name). Mostly useful when no --token-id is
specified.
--sector-size <bytes>
Set sector size for use with disk encryption. It must be
power of two and in range 512 - 4096 bytes. This option is
available only in the LUKS2 or plain modes.
The default for plain mode is 512 bytes. For LUKS2 devices
it's established during luksFormat operation based on
parameters provided by underlying data device. For native
4K block devices it's 4096 bytes. For 4K/512e (4K physical
sector size with 512 bytes emulation) it's 4096 bytes. For
drives reporting only 512 bytes block size it remains 512
bytes. If data device is regular file put in filesystem
it's 4096 bytes.
Note that if sector size is higher than underlying device
hardware sector and there is not integrity protection that
uses data journal, 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 it cost 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 and also with some hw encryption accelerators.
--iv-large-sectors
Count Initialization Vector (IV) in larger sector size (if
set) instead of 512 bytes sectors. This option can be used
only for open command and plain encryption type.
NOTE: This option does not have any performance or
security impact, use it only for accessing incompatible
existing disk images from other systems that require this
option.
--persistent
If used with LUKS2 devices and activation commands like
open or refresh, the specified activation flags are
persistently written into metadata and used next time
automatically even for normal activation. (No need to use
cryptab or other system configuration files.)
If you need to remove a persistent flag, use --persistent
without the flag you want to remove (e.g. to disable
persistently stored discard flag, use --persistent without
--allow-discards).
Only --allow-discards, --perf-same_cpu_crypt,
--perf-submit_from_crypt_cpus, --perf-no_read_workqueue,
--perf-no_write_workqueue and --integrity-no-journal can
be stored persistently.
--refresh
Refreshes an active device with new set of parameters. See
action refresh description for more details.
--label <LABEL>
--subsystem <SUBSYSTEM> Set label and subsystem
description for LUKS2 device, can be used in config and
format actions. The label and subsystem are optional
fields and can be later used in udev scripts for
triggering user actions once device marked by these labels
is detected.
--integrity <integrity algorithm>
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). For native AEAD modes, also enable "User-space
interface for AEAD cipher algorithms" in "Cryptographic
API" section (CONFIG_CRYPTO_USER_API_AEAD .config option).
For more info, see AUTHENTICATED DISK ENCRYPTION section.
--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 LUKS2 specification, only these values are
valid: 16, 32, 64, 128, 256, 512, 1024, 2048 and 4096 kB
The <size> can be specified with unit suffix (for example
128k).
--luks2-keyslots-size <size>
This option can be used to set specific size of the LUKS2
binary keyslot area (key material is encrypted there). The
value must be aligned to multiple of 4096 bytes with
maximum size 128MB. The <size> can be specified with unit
suffix (for example 128k).
--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 specific key size for the
LUKS2 keyslot area.
--integrity-no-journal
Activate device with integrity protection without using
data journal (direct write of data and integrity tags).
Note that without journal power fail can cause non-atomic
write and data corruption. Use only if journalling is
performed on a different storage layer.
--integrity-no-wipe
Skip wiping of device authentication (integrity) tags. If
you skip this step, sectors will report invalid integrity
tag until an 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 sector with invalid integrity tag.
--unbound
Creates new or dumps existing LUKS2 unbound keyslot. See
luksAddKey or luksDump actions for more details.
--tcrypt-hidden
--tcrypt-system --tcrypt-backup Specify which TrueCrypt
on-disk header will be used to open the device. See
TCRYPT section for more info.
--veracrypt
This option is ignored as VeraCrypt compatible mode is
supported by default.
--disable-veracrypt
This option can be used to disable VeraCrypt compatible
mode (only TrueCrypt devices are recognized). Only for
TCRYPT extension. See TCRYPT section for more info.
--veracrypt-pim
--veracrypt-query-pim Use a custom Personal Iteration
Multiplier (PIM) for VeraCrypt device. See TCRYPT section
for more info.
--serialize-memory-hard-pbkdf
Use a global lock to serialize unlocking of keyslots using
memory-hard PBKDF.
NOTE: This is (ugly) workaround for a specific situation
when multiple devices are activated in parallel and system
instead of reporting out of memory starts unconditionally
stop processes using out-of-memory killer.
DO NOT USE this switch until you are implementing boot
environment with parallel devices activation!
--encrypt
Initialize (and run) device encryption (reencrypt action
parameter)
--decrypt
Initialize (and run) device decryption (reencrypt action
parameter)
--init-only
Initialize reencryption (any variant) operation in LUKS2
metadata only and exit. If any reencrypt operation is
already initialized in metadata, the command with
--init-only parameter fails.
--resume-only
Resume reencryption (any variant) operation already
described in LUKS2 metadata. If no reencrypt operation is
initialized, the command with --resume-only parameter
fails. Useful for resuming reencrypt operation without
accidentally triggering new reencryption operation.
--resilience <mode>
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 old offline reencryption utility. (ctrl+c).
The option is ignored if reencryption with datashift mode
is in progress.
--resilience-hash <hash>
The hash algorithm used with "--resilience checksum" only.
The default hash is sha256. With other resilience modes,
the hash parameter is ignored.
--hotzone-size <size>
This option can be used to set an upper limit on the size
of reencryption area (hotzone). The <size> can be
specified with unit suffix (for example 50M). Note that
actual hotzone size may be less than specified <size> due
to other limitations (free space in keyslots area or
available memory).
--reduce-device-size <size>
Initialize LUKS2 reencryption with data device size
reduction (currently only --encrypt variant is supported).
Last <size> sectors of <device> will be used to properly
initialize device reencryption. That means any data at
last <size> sectors will be lost.
It could be useful if you added some space to underlying
partition or logical volume (so last <size> sectors
contains no data).
Recommended minimal size is twice the default LUKS2 header
size (--reduce-device-size 32M) for --encrypt use case. Be
sure to have enough (at least --reduce-device-size value
of free space at the end of <device>).
WARNING: This is a destructive operation and cannot be
reverted. Use with extreme care - accidentally
overwritten filesystems are usually unrecoverable.
--version
Show the program version.
--usage
Show short option help.
--help, -?
Show help text and default parameters.
