-.TH CRYPTSETUP "8" "January 2019" "cryptsetup" "Maintenance Commands"
+.TH CRYPTSETUP "8" "January 2021" "cryptsetup" "Maintenance Commands"
.SH NAME
cryptsetup - manage plain dm-crypt and LUKS encrypted volumes
.SH SYNOPSIS
container creation. If you do not know how to do that, the
cryptsetup FAQ describes several options.
-.SH BASIC COMMANDS
+.SH BASIC ACTIONS
The following are valid actions for all supported device types.
\fIopen\fR <device> <name> \-\-type <device_type>
devices: LUKS1, LUKS2 (including authenticated encryption), plain crypt
and loopaes.
-Mandatory parametrs are identical to those of an open action for respective
+Mandatory parameters are identical to those of an open action for respective
device type.
You may change following parameters on all devices \-\-perf\-same_cpu_crypt,
-\-\-perf\-submit_from_crypt_cpus and \-\-allow\-discards.
+\-\-perf\-submit_from_crypt_cpus, \-\-perf-no_read_workqueue, \-\-perf-no_write_workqueue
+and \-\-allow\-discards.
Refreshing device without any optional parameter will refresh the device
with default setting (respective to device type).
Action supports following additional \fB<options>\fR [\-\-encrypt, \-\-decrypt, \-\-device\-size,
\-\-resilience, \-\-resilience-hash, \-\-hotzone-size, \-\-init\-only, \-\-resume\-only,
-\-\-reduce\-device\-size].
+\-\-reduce\-device\-size, \-\-master\-key\-file, \-\-key\-size].
.SH PLAIN MODE
Plain dm-crypt encrypts the device sector-by-sector with a
give '-' as file name, which results in the passphrase being read
from stdin and the safety-question being skipped.
-You can only call luksFormat on a LUKS device that is not mapped.
+You cannot call luksFormat on a device or filesystem that is mapped or in use,
+e.g. mounted filesysem, used in LVM, active RAID member etc.
+The device or filesystem has to be un-mounted in order to call luksFormat.
To use LUKS2, specify \fI\-\-type luks2\fR.
\fB<options>\fR can be [\-\-key\-file, \-\-tcrypt\-hidden,
\-\-tcrypt\-system, \-\-tcrypt\-backup, \-\-readonly, \-\-test\-passphrase,
-\-\-allow-discards, \-\-veracrypt, \-\-veracrypt\-pim, \-\-veracrypt\-query\-pim].
+\-\-allow-discards, \-\-veracrypt, \-\-veracrypt\-pim, \-\-veracrypt\-query\-pim,
+\-\-header].
The keyfile parameter allows a combination of file content with the
passphrase and can be repeated. Note that using keyfiles is compatible
with TCRYPT and is different from LUKS keyfile logic.
+If you use \fB\-\-header\fR in combination with hidden or system options,
+the header file must contain specific headers on the same positions as the original
+encrypted container.
+
\fBWARNING:\fR Option \fB\-\-allow\-discards\fR cannot be combined with
option \fB\-\-tcrypt\-hidden\fR. For normal mapping, it can cause
the \fBdestruction of hidden volume\fR (hidden volume appears as unused space
any key-slot data. You may enforce LUKS version by adding \-\-type
option.
+It also repairs (upgrades) LUKS2 reencryption metadata by adding
+metadata digest that protects it against malicious changes.
+
+If LUKS2 reencryption was interrupted in the middle of writting
+reencryption segment the repair command can be used to perform
+reencryption recovery so that reencryption can continue later.
+
\fBWARNING:\fR Always create a binary backup of the original
header before calling this command.
.PP
If \-\-debug\-json is used, additional LUKS2 JSON data structures are printed.
.TP
.B "\-\-type <device-type>
-Specifies required device type, for more info
-read \fIBASIC COMMANDS\fR section.
+Specifies required device type, for more info read \fIBASIC ACTIONS\fR section.
.TP
.B "\-\-hash, \-h \fI<hash\-spec>\fR"
Specifies the passphrase hash for \fIopen\fR (for plain and
all parameters directly, use \fI\-\-pbkdf\-force\-iterations\fR with
\fI\-\-pbkdf\-memory\fR and \fI\-\-pbkdf\-parallel\fR.
This will override the values without benchmarking.
-Note it can cause extremely long unlocking time. Use only is specified
+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.
In this case, the LUKS PBKDF2 digest will be set to the minimum iteration count.
performance tuning, use only if you need a change to default dm-crypt
behaviour. Needs kernel 4.0 or later.
.TP
+.B "\-\-perf\-no_read_workqueue, \-\-perf\-no_write_workqueue\fR"
+Bypass dm-crypt internal workqueue and process read or write requests
+synchronously.
+This option is only relevant for \fIopen\fR action.
+
+\fBNOTE:\fR 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.
+.TP
.B "\-\-test\-passphrase\fR"
Do not activate the device, just verify passphrase.
This option is only relevant for \fIopen\fR action (the device
use \fI\-\-persistent\fR without \fI\-\-allow-discards\fR).
Only \fI\-\-allow-discards\fR, \fI\-\-perf\-same_cpu_crypt\fR,
-\fI\-\-perf\-submit_from_crypt_cpus\fR and \fI\-\-integrity\-no\-journal\fR
+\fI\-\-perf\-submit_from_crypt_cpus\fR, \fI\-\-perf\-no_read_workqueue\fR,
+\fI\-\-perf\-no_write_workqueue\fR and \fI\-\-integrity\-no\-journal\fR
can be stored persistently.
.TP
.B "\-\-refresh"
Reencryption resilience mode can be one of \fIchecksum\fR, \fIjournal\fR or \fInone\fR.
\fIchecksum\fR: default mode, where individual checksums of ciphertext hotzone sectors are stored,
-so the recovery process can detect which sectors where already reencrypted. It requires that the device sector write is atomic.
+so the recovery process can detect which sectors where already reencrypted.
+It requires that the device sector write is atomic.
\fIjournal\fR: the hotzone is journaled in the binary area (so the data are written twice).
The option is ignored if reencryption with datashift mode is in progress.
.TP
.B "\-\-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.
+The hash algorithm used with "\-\-resilience checksum" only.
+The default hash is sha256. With other resilience modes, the hash parameter is ignored.
.TP
.B "\-\-hotzone-size <size>"
This option can be used to set an upper limit on the size of reencryption area (hotzone).
available memory).
.TP
.B "\-\-reduce\-device\-size <size>"
-Initialize LUKS2 reencryption with data device size reduction (currently only \-\-encrypt variant is supported).
+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.
+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).
+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>).
+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.
+WARNING: This is a destructive operation and cannot be reverted.
+Use with extreme care - accidentally overwritten filesystems are usually unrecoverable.
.TP
.B "\-\-version"
Show the program version.
.TP
.B "\-\-help, \-?"
Show help text and default parameters.
+.SH EXAMPLE
+.TP
+Example 1: Create LUKS 2 container on block device /dev/sdX.
+sudo cryptsetup --type luks2 luksFormat /dev/sdX
+.TP
+Example 2: Add an additional passphrase to key slot 5.
+sudo cryptsetup luksAddKey --key-slot 5 /dev/sdX
+.TP
+Example 3: Create LUKS header backup and save it to file.
+sudo cryptsetup luksHeaderBackup /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile
+.TP
+Example 4: Open LUKS contaner on /dev/sdX and map it to sdX_crypt.
+sudo cryptsetup open /dev/sdX sdX_crypt
+.TP
+.B WARNING: The command in example 5 will erase all key slots.
+Your cannot use your luks container afterwards anymore unless you have a backup to restore.
+.TP
+Example 5: Erase all key slots on /dev/sdX.
+sudo cryptsetup erase /dev/sdX
+.TP
+Example 6: Restore LUKS header from backup file.
+sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile
.SH RETURN CODES
Cryptsetup returns 0 on success and a non-zero value on error.
\fBWARNING:\fR All support for authenticated modes is experimental
and there are only some modes available for now. Note that there
are a very few authenticated encryption algorithms that are suitable
-for disk encryption.
+for disk encryption. You also cannot use CRC32 or any other non-cryptographic
+checksums (other than the special integrity mode "none"). If for some reason
+you want to have integrity control without using authentication mode, then you
+should separately configure dm-integrity independently of LUKS2.
.SH NOTES ON LOOPBACK DEVICE USE
Cryptsetup is usually used directly on a block device (disk
.br
Copyright \(co 2012-2014 Arno Wagner
.br
-Copyright \(co 2009-2020 Red Hat, Inc.
+Copyright \(co 2009-2021 Red Hat, Inc.
.br
-Copyright \(co 2009-2020 Milan Broz
+Copyright \(co 2009-2021 Milan Broz
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
The cryptsetup mailing list and list archive, see FAQ entry 1.6.
-The LUKS on-disk format specification available at
-\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/Specification\fR
+The LUKS version 1 on-disk format specification available at
+\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/Specification\fR and
+LUKS version 2 at \fBhttps://gitlab.com/cryptsetup/LUKS2-docs\fR.
projects / platform / upstream / cryptsetup.git / blobdiff