From 1660d4b7a65d9ad2ce0deaa19d35579ca4084ac5 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 10:06:26 +0200 Subject: Adding upstream version 2:2.6.1. Signed-off-by: Daniel Baumann --- man/Makemodule.am | 145 ++++ man/common_footer.adoc | 17 + man/common_options.adoc | 1195 +++++++++++++++++++++++++++++++ man/cryptsetup-benchmark.8.adoc | 41 ++ man/cryptsetup-bitlkDump.8.adoc | 34 + man/cryptsetup-close.8.adoc | 30 + man/cryptsetup-config.8.adoc | 30 + man/cryptsetup-convert.8.adoc | 37 + man/cryptsetup-erase.8.adoc | 28 + man/cryptsetup-fvault2Dump.8.adoc | 34 + man/cryptsetup-isLuks.8.adoc | 29 + man/cryptsetup-luksAddKey.8.adoc | 71 ++ man/cryptsetup-luksChangeKey.8.adoc | 46 ++ man/cryptsetup-luksConvertKey.8.adoc | 41 ++ man/cryptsetup-luksDump.8.adoc | 50 ++ man/cryptsetup-luksFormat.8.adoc | 51 ++ man/cryptsetup-luksHeaderBackup.8.adoc | 35 + man/cryptsetup-luksHeaderRestore.8.adoc | 34 + man/cryptsetup-luksKillSlot.8.adoc | 40 ++ man/cryptsetup-luksRemoveKey.8.adoc | 33 + man/cryptsetup-luksResume.8.adoc | 29 + man/cryptsetup-luksSuspend.8.adoc | 33 + man/cryptsetup-luksUUID.8.adoc | 25 + man/cryptsetup-open.8.adoc | 165 +++++ man/cryptsetup-reencrypt.8.adoc | 175 +++++ man/cryptsetup-refresh.8.adoc | 53 ++ man/cryptsetup-repair.8.adoc | 43 ++ man/cryptsetup-resize.8.adoc | 42 ++ man/cryptsetup-ssh.8.adoc | 80 +++ man/cryptsetup-status.8.adoc | 24 + man/cryptsetup-tcryptDump.8.adoc | 37 + man/cryptsetup-token.8.adoc | 55 ++ man/cryptsetup.8.adoc | 729 +++++++++++++++++++ man/integritysetup.8.adoc | 334 +++++++++ man/veritysetup.8.adoc | 311 ++++++++ 35 files changed, 4156 insertions(+) create mode 100644 man/Makemodule.am create mode 100644 man/common_footer.adoc create mode 100644 man/common_options.adoc create mode 100644 man/cryptsetup-benchmark.8.adoc create mode 100644 man/cryptsetup-bitlkDump.8.adoc create mode 100644 man/cryptsetup-close.8.adoc create mode 100644 man/cryptsetup-config.8.adoc create mode 100644 man/cryptsetup-convert.8.adoc create mode 100644 man/cryptsetup-erase.8.adoc create mode 100644 man/cryptsetup-fvault2Dump.8.adoc create mode 100644 man/cryptsetup-isLuks.8.adoc create mode 100644 man/cryptsetup-luksAddKey.8.adoc create mode 100644 man/cryptsetup-luksChangeKey.8.adoc create mode 100644 man/cryptsetup-luksConvertKey.8.adoc create mode 100644 man/cryptsetup-luksDump.8.adoc create mode 100644 man/cryptsetup-luksFormat.8.adoc create mode 100644 man/cryptsetup-luksHeaderBackup.8.adoc create mode 100644 man/cryptsetup-luksHeaderRestore.8.adoc create mode 100644 man/cryptsetup-luksKillSlot.8.adoc create mode 100644 man/cryptsetup-luksRemoveKey.8.adoc create mode 100644 man/cryptsetup-luksResume.8.adoc create mode 100644 man/cryptsetup-luksSuspend.8.adoc create mode 100644 man/cryptsetup-luksUUID.8.adoc create mode 100644 man/cryptsetup-open.8.adoc create mode 100644 man/cryptsetup-reencrypt.8.adoc create mode 100644 man/cryptsetup-refresh.8.adoc create mode 100644 man/cryptsetup-repair.8.adoc create mode 100644 man/cryptsetup-resize.8.adoc create mode 100644 man/cryptsetup-ssh.8.adoc create mode 100644 man/cryptsetup-status.8.adoc create mode 100644 man/cryptsetup-tcryptDump.8.adoc create mode 100644 man/cryptsetup-token.8.adoc create mode 100644 man/cryptsetup.8.adoc create mode 100644 man/integritysetup.8.adoc create mode 100644 man/veritysetup.8.adoc (limited to 'man') diff --git a/man/Makemodule.am b/man/Makemodule.am new file mode 100644 index 0000000..41e21da --- /dev/null +++ b/man/Makemodule.am @@ -0,0 +1,145 @@ +ADOCFILES_COMMON = \ + man/common_options.adoc \ + man/common_footer.adoc + +ADOCFILES = $(ADOCFILES_COMMON) \ + man/cryptsetup.8.adoc \ + man/cryptsetup-open.8.adoc \ + man/cryptsetup-close.8.adoc \ + man/cryptsetup-reencrypt.8.adoc \ + man/cryptsetup-status.8.adoc \ + man/cryptsetup-resize.8.adoc \ + man/cryptsetup-refresh.8.adoc \ + man/cryptsetup-luksFormat.8.adoc \ + man/cryptsetup-luksSuspend.8.adoc \ + man/cryptsetup-luksResume.8.adoc \ + man/cryptsetup-luksAddKey.8.adoc \ + man/cryptsetup-luksRemoveKey.8.adoc \ + man/cryptsetup-luksConvertKey.8.adoc \ + man/cryptsetup-luksKillSlot.8.adoc \ + man/cryptsetup-luksChangeKey.8.adoc \ + man/cryptsetup-erase.8.adoc \ + man/cryptsetup-luksUUID.8.adoc \ + man/cryptsetup-isLuks.8.adoc \ + man/cryptsetup-luksDump.8.adoc \ + man/cryptsetup-luksHeaderBackup.8.adoc \ + man/cryptsetup-luksHeaderRestore.8.adoc \ + man/cryptsetup-token.8.adoc \ + man/cryptsetup-convert.8.adoc \ + man/cryptsetup-config.8.adoc \ + man/cryptsetup-tcryptDump.8.adoc \ + man/cryptsetup-bitlkDump.8.adoc \ + man/cryptsetup-fvault2Dump.8.adoc \ + man/cryptsetup-repair.8.adoc \ + man/cryptsetup-benchmark.8.adoc \ + man/cryptsetup-ssh.8.adoc \ + man/veritysetup.8.adoc \ + man/integritysetup.8.adoc + +dist_noinst_DATA += $(ADOCFILES) + +CRYPTSETUP_MANPAGES = \ + man/cryptsetup.8 \ + man/cryptsetup-open.8 \ + man/cryptsetup-close.8 \ + man/cryptsetup-reencrypt.8 \ + man/cryptsetup-status.8 \ + man/cryptsetup-resize.8 \ + man/cryptsetup-refresh.8 \ + man/cryptsetup-luksFormat.8 \ + man/cryptsetup-luksSuspend.8 \ + man/cryptsetup-luksResume.8 \ + man/cryptsetup-luksAddKey.8 \ + man/cryptsetup-luksRemoveKey.8 \ + man/cryptsetup-luksConvertKey.8 \ + man/cryptsetup-luksKillSlot.8 \ + man/cryptsetup-luksChangeKey.8 \ + man/cryptsetup-erase.8 \ + man/cryptsetup-luksUUID.8 \ + man/cryptsetup-isLuks.8 \ + man/cryptsetup-luksDump.8 \ + man/cryptsetup-luksHeaderBackup.8 \ + man/cryptsetup-luksHeaderRestore.8 \ + man/cryptsetup-token.8 \ + man/cryptsetup-convert.8 \ + man/cryptsetup-config.8 \ + man/cryptsetup-tcryptDump.8 \ + man/cryptsetup-bitlkDump.8 \ + man/cryptsetup-fvault2Dump.8 \ + man/cryptsetup-repair.8 \ + man/cryptsetup-benchmark.8 + +CRYPTSETUP_MANLINKS = \ + man/cryptsetup-create.8 \ + man/cryptsetup-plainOpen.8 \ + man/cryptsetup-luksOpen.8 \ + man/cryptsetup-loopaesOpen.8 \ + man/cryptsetup-tcryptOpen.8 \ + man/cryptsetup-bitlkOpen.8 \ + man/cryptsetup-fvault2Open.8 \ + man/cryptsetup-luksErase.8 + +VERITYSETUP_MANPAGES = man/veritysetup.8 +INTEGRITYSETUP_MANPAGES = man/integritysetup.8 +SSHPLUGIN_MANPAGES = man/cryptsetup-ssh.8 + +MANPAGES_ALL = \ + $(CRYPTSETUP_MANPAGES) \ + $(CRYPTSETUP_MANLINKS) \ + $(VERITYSETUP_MANPAGES) \ + $(INTEGRITYSETUP_MANPAGES) \ + $(SSHPLUGIN_MANPAGES) + +MANPAGES = +MANLINKS = + +if CRYPTSETUP +MANPAGES += $(CRYPTSETUP_MANPAGES) +MANLINKS += $(CRYPTSETUP_MANLINKS) +endif +if VERITYSETUP +MANPAGES += $(VERITYSETUP_MANPAGES) +endif +if INTEGRITYSETUP +MANPAGES += $(INTEGRITYSETUP_MANPAGES) +endif +if SSHPLUGIN_TOKEN +MANPAGES += $(SSHPLUGIN_MANPAGES) +endif + +if ENABLE_ASCIIDOC +EXTRA_DIST += $(MANPAGES_ALL) +man8_MANS += $(MANPAGES) $(MANLINKS) + +$(MANPAGES): $(ADOCFILES_COMMON) + +SUFFIXES = .8.adoc .8 +.8.adoc.8: + $(AM_V_GEN) $(ASCIIDOCTOR) -b manpage \ + -a 'release-version=$(VERSION)' \ + --base-dir=$(abs_srcdir) \ + --destination-dir $(abs_builddir)/man $< + +$(MANLINKS): $(MANPAGES) +gen-man: $(man8_MANS) + +gen-man-dist: + @list=`find -name *.adoc -not -path "*/man/common_*" | sed -e 's/\.adoc//g'`; \ + missing=`for p in $$list; do test -f $$p || echo $$p; done`; \ + if test -n "$$missing"; then \ + $(MAKE) $(AM_MAKEFLAGS) $$missing; \ + fi; + +# !ENABLE_ASCIIDOC +else + +if HAVE_MANPAGES +EXTRA_DIST += $(MANPAGES_ALL) +man8_MANS += $(MANPAGES) $(MANLINKS) +endif + +gen-man: +gen-man-dist: +endif + +dist-hook: gen-man-dist diff --git a/man/common_footer.adoc b/man/common_footer.adoc new file mode 100644 index 0000000..21302eb --- /dev/null +++ b/man/common_footer.adoc @@ -0,0 +1,17 @@ + +== REPORTING BUGS + +Report bugs at mailto:cryptsetup@lists.linux.dev[*cryptsetup mailing list*] +or in https://gitlab.com/cryptsetup/cryptsetup/-/issues/new[*Issues project section*]. + +Please attach output of the failed command with --debug option added. + +== SEE ALSO + +https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions[*Cryptsetup FAQ*] + +*cryptsetup*(8), *integritysetup*(8) and *veritysetup*(8) + +== CRYPTSETUP + +Part of https://gitlab.com/cryptsetup/cryptsetup/[*cryptsetup project*]. diff --git a/man/common_options.adoc b/man/common_options.adoc new file mode 100644 index 0000000..56a6e29 --- /dev/null +++ b/man/common_options.adoc @@ -0,0 +1,1195 @@ +== OPTIONS + +ifdef::ACTION_REENCRYPT[] +*--block-size* _value_ *(LUKS1 only)*:: +Use re-encryption block size of _value_ in MiB. ++ +Values can be between 1 and 64 MiB. +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--use-directio (LUKS1 only)*:: +Use direct-io (O_DIRECT) for all read/write data operations related +to block device undergoing reencryption. ++ +Useful if direct-io operations perform better than normal buffered +operations (e.g. in virtual environments). +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--use-fsync (LUKS1 only)*:: +Use fsync call after every written block. This applies for reencryption +log files as well. +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--write-log (LUKS1 only)*:: +Update log file after every block write. This can slow down reencryption +but will minimize data loss in the case of system crash. +endif::[] + +ifdef::ACTION_ISLUKS[] +*--verbose, -v*:: +Print more information on command execution. +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSKILLSLOT,ACTION_ISLUKS,ACTION_LUKSDUMP,ACTION_LUKSUUID,ACTION_CONVERT,ACTION_REPAIR,ACTION_REENCRYPT[] +*--type *:: +ifndef::ACTION_REENCRYPT[] +Specifies required device type, for more info read _BASIC ACTIONS_ section in *cryptsetup*(8). +endif::[] +ifdef::ACTION_REENCRYPT[] +Specifies required (encryption mode) or expected (other modes) LUKS format. Accepts only _luks1_ or _luks2_. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_TCRYPTDUMP,ACTION_BENCHMARK,ACTION_REENCRYPT[] +*--hash, -h* __:: +ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] +Specifies the passphrase hash. Applies to _plain_ and _loopaes_ device types only. ++ +For _tcrypt_ device type, it restricts checked PBKDF2 variants when looking for header. +endif::[] +ifdef::ACTION_LUKSFORMAT[] +Specifies the hash used in the LUKS key setup scheme and volume key +digest. +endif::[] +ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_TCRYPTDUMP[] +The specified hash is used for PBKDF2 and AF splitter. +endif::[] +ifdef::ACTION_REENCRYPT[] +*LUKS1:* +Specifies the hash used in the LUKS1 key setup scheme and volume key digest. ++ +*NOTE*: if this parameter is not specified, default hash algorithm is always used +for new LUKS1 device header. ++ +*LUKS2:* Ignored unless new keyslot pbkdf algorithm is set to PBKDF2 (see --pbkdf). +endif::[] ++ +ifdef::ACTION_LUKSFORMAT[] +The hash algorithm must provide at least 160 bits of output. +Do not use a non-crypto hash like *xxhash* as this breaks security. +Use _cryptsetup --help_ to show the defaults. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_TCRYPTDUMP,ACTION_BENCHMARK[] +*--cipher, -c* __:: +ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] +Set the cipher specification string for _plain_ device type. ++ +For _tcrypt_ device type it restricts checked cipher chains when looking for header. +endif::[] +ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_TCRYPTDUMP[] +Set the cipher specification string. +endif::[] +ifdef::ACTION_REENCRYPT[] +*LUKS2*: +Set the cipher specification string for data segment only. ++ +*LUKS1*: +Set the cipher specification string for data segment and keyslots. ++ +*NOTE*: In encrypt mode, if cipher specification is omitted the default cipher is applied. +In reencrypt mode, if no new cipher specification is requested, the existing cipher will remain +in use. Unless the existing cipher was "cipher_null". In that case default cipher would +be applied as in encrypt mode. +endif::[] +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] ++ +_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. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_REPAIR,ACTION_TCRYPTDUMP,ACTION_REENCRYPT[] +*--verify-passphrase, -y*:: +When interactively asking for a passphrase, ask for it twice and +complain if both inputs do not match. +ifdef::ACTION_OPEN[] +Advised when creating a _plain_ type mapping for the first time. +endif::[] +Ignored on input from file or stdin. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_TCRYPTDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[] +*--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. ++ +ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY[] +The passphrase supplied via --key-file is always the passphrase for existing +keyslot requested by the command. ++ +If you want to set a new passphrase via key file, you have to use a +positional argument or parameter --new-keyfile. ++ +endif::[] +ifdef::ACTION_OPEN[] +*NOTE:* With _plain_ device type, the passphrase obtained via --key-file option is +passed directly in dm-crypt. Unlike the interactive mode (stdin) +where digest (--hash option) of the passphrase is passed in dm-crypt instead. ++ +endif::[] +ifndef::ACTION_REENCRYPT[] +See section _NOTES ON PASSPHRASE PROCESSING_ in *cryptsetup*(8) for more information. +endif::[] +ifdef::ACTION_REENCRYPT[] +*WARNING:* --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 new LUKS device). ++ +If this option is not used, cryptsetup will ask for all active keyslot +passphrases. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[] +*--keyfile-offset* _value_:: +Skip _value_ bytes at the beginning of the key file. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[] +*--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. +endif::[] + +ifdef::ACTION_LUKSADDKEY[] +*--new-keyfile* _name_:: +Read the passphrase for a new keyslot 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. ++ +This is alternative method to positional argument when adding new +passphrase via kefile. +endif::[] + +ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY[] +*--new-keyfile-offset* _value_:: +Skip _value_ bytes at the start when adding a new passphrase from key +file. +endif::[] + +ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY[] +*--new-keyfile-size* _value_:: +Read a maximum of _value_ bytes when adding a new passphrase from key +file. 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. +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_BITLKDUMP,ACTION_REENCRYPT[] +*--volume-key-file, --master-key-file (OBSOLETE alias)*:: +ifndef::ACTION_REENCRYPT[] +Use a volume key stored in a file. +endif::[] +ifdef::ACTION_FORMAT[] ++ +This allows creating a LUKS header with this specific +volume key. If the volume 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 volume key was taken from. + +endif::[] +ifdef::ACTION_LUKSDUMP,ACTION_BITLKDUMP[] +The volume key is stored in a file instead of being printed out to standard output. + +endif::[] +ifdef::ACTION_LUKSADDKEY[] +This allows adding a new keyslot without having to know passphrase to existing one. +It may be also used when no keyslot is active. ++ +endif::[] +ifdef::ACTION_OPEN[] +This allows one to open _luks_ and _bitlk_ device types without giving a passphrase. + +endif::[] +ifdef::ACTION_REENCRYPT[] +Use (set) new volume key stored in a file. + +endif::[] +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_REENCRYPT[] +*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. +endif::[] +endif::[] + +ifdef::ACTION_LUKSDUMP[] +*--dump-json-metadata*:: +For _luksDump_ (LUKS2 only) this option prints content of LUKS2 header +JSON metadata area. +endif::[] + +ifdef::ACTION_LUKSDUMP,ACTION_TCRYPTDUMP,ACTION_BITLKDUMP[] +*--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. +endif::[] + +ifdef::ACTION_TOKEN[] +*--json-file*:: +Read token JSON from a file or write token to it. --json-file=- reads JSON from +standard input or writes it to standard output respectively. +endif::[] + +ifdef::ACTION_TOKEN[] +*--token-replace*:: +Replace an existing token when adding or importing a token with the +--token-id option. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--use-random*:: +*--use-urandom*:: +ifdef::ACTION_REENCRYPT[] +Define which kernel random number generator will be used to create the volume key. +endif::[] +ifndef::ACTION_REENCRYPT[] +For _luksFormat_ these options define which kernel random number +generator will be used to create the volume key (which is a long-term +key). ++ +See *NOTES ON RANDOM NUMBER GENERATORS* in *cryptsetup*(8) 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) and older +kernels, 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. +endif::[] +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--keep-key*:: +*LUKS2*: +Do not change effective volume key and change other parameters provided +it is requested. ++ +*LUKS1*: +Reencrypt only the LUKS1 header and keyslots. Skips data in-place reencryption. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSDUMP,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_CONFIG,ACTION_TOKEN,ACTION_REPAIR,ACTION_REENCRYPT[] +*--key-slot, -S <0-N>*:: +ifdef::ACTION_LUKSADDKEY[] +When used together with parameter --new-key-slot this option allows you to specify which +key slot is selected for unlocking volume key. ++ +*NOTE:* This option is ignored if existing volume key gets unlocked +via LUKS2 token (--token-id, --token-type or --token-only parameters) or +when volume key is provided directly via --volume-key-file parameter. ++ +*NOTE:* To maintain backward compatibility, without --new-key-slot parameter, +this option allows you to specify which key slot is selected for the new key. +endif::[] +ifndef::ACTION_OPEN,ACTION_LUKSADDKEY[] +For LUKS operations that add key material, this option allows you to +specify which key slot is selected for the new key. +endif::[] +ifdef::ACTION_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. +endif::[] ++ +ifdef::ACTION_REENCRYPT[] +For reencryption mode it selects specific keyslot (and passphrase) that can be used to unlock new volume key. +If used all other keyslots get removed after reencryption operation is finished. ++ +endif::[] +The maximum number of key slots depends on the LUKS version. LUKS1 can have up +to 8 key slots. LUKS2 can have up to 32 key slots based on key slot area +size and key size, but a valid key slot ID can always be between 0 and +31 for LUKS2. +endif::[] + +ifdef::ACTION_LUKSADDKEY[] +*--new-key-slot <0-N>*:: +This option allows you to specify which key slot is selected for +the new key. ++ +*NOTE:* When used this option affects --key-slot option. ++ +The maximum number of key slots depends on the LUKS version. LUKS1 can have up +to 8 key slots. LUKS2 can have up to 32 key slots based on key slot area +size and key size, but a valid key slot ID can always be between 0 and +31 for LUKS2. +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_BENCHMARK,ACTION_LUKSADDKEY[] +*--key-size, -s* _bits_:: +ifndef::ACTION_LUKSADDKEY[] +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. ++ +endif::[] +ifdef::ACTION_LUKSADDKEY[] +Provide volume key size in _bits_. The argument has to be a multiple of 8. ++ +This option is required when parameter --volume-key-file is used to provide +current volume key. Also, it is used when new unbound keyslot is created by +specifying --unbound parameter. +endif::[] +ifdef::ACTION_OPEN[] +This option can be used for _plain_ device type only. +endif::[] +ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_LUKSADDKEY[] +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. +endif::[] +ifdef::ACTION_REENCRYPT[] +*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 new key size, +you can destructively shrink device with --reduce-device-size option. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE[] +*--size, -b *:: +Set the size of the device in sectors of 512 bytes. +ifdef::ACTION_OPEN[] +Usable only with _plain_ device type. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--offset, -o *:: +Start offset in the backend device in 512-byte sectors. +ifdef::ACTION_OPEN[] +This option is only relevant with plain or loopaes device types. +endif::[] +ifdef::ACTION_REENCRYPT[] +This option is only relevant for the encrypt mode. +endif::[] ++ +ifndef::ACTION_OPEN[] +The --offset option sets the data offset (payload) of data +device and must be aligned to 4096-byte sectors (must be multiple of +8). This option cannot be combined with --align-payload option. +endif::[] +endif::[] + +ifdef::ACTION_OPEN[] +*--skip, -p *:: +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. +endif::[] + +ifdef::ACTION_OPEN,ACTION_REENCRYPT,ACTION_RESIZE[] +*--device-size* _size[units]_:: +ifndef::ACTION_RESIZE[] +Instead of real device size, use specified value. +endif::[] +ifdef::ACTION_RESIZE[] +Sets new size of the device. If unset real device size is used. +endif::[] +ifdef::ACTION_OPEN[] +Usable only with _plain_ device type. +endif::[] +ifdef::ACTION_REENCRYPT[] +It means that only specified area (from the start of the device +to the specified size) will be reencrypted. ++ +*WARNING:* This is destructive operation. Data beyond --device-size limit may +be lost after operation gets finished. +endif::[] ++ +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). +endif::[] + +ifdef::ACTION_OPEN[] +*--readonly, -r*:: +set up a read-only mapping. +endif::[] + +ifdef::ACTION_OPEN[] +*--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. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] +*--pbkdf *:: +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[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 _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 +*cryptsetup-luksDump*(8) 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 addressable 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). +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] +*--iter-time, -i *:: +ifndef::ACTION_REENCRYPT[] +The number of milliseconds to spend with PBKDF passphrase processing. +Specifying 0 as parameter selects the compiled-in default. +endif::[] +ifdef::ACTION_REENCRYPT[] +The number of milliseconds to spend with PBKDF passphrase processing for the +new LUKS header. +endif::[] +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] +*--pbkdf-memory *:: +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. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] +*--pbkdf-parallel *:: +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. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] +*--pbkdf-force-iterations *:: +Avoid PBKDF benchmark and set time cost (iterations) directly. It can +be used for LUKS/LUKS2 device only. See _--pbkdf_ option for more +info. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--progress-frequency* _seconds_:: +ifndef::ACTION_REENCRYPT[] +Print separate line every _seconds_ with wipe progress. +endif::[] +ifdef::ACTION_REENCRYPT[] +Print separate line every _seconds_ with reencryption progress. +endif::[] +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--progress-json*:: +Prints progress data in JSON format suitable mostly for machine +processing. It prints separate line every half second (or based on +_--progress-frequency_ value). The JSON output looks as follows during +progress (except it's 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 parsers limitations all +numbers are represented in a string format due to need of full 64bit +unsigned integers. +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_LUKSRESUME,ACTION_RESIZE,ACTION_TCRYPTDUMP,ACTION_BITLKDUMP[] +*--timeout, -t *:: +The number of seconds to wait before timeout on passphrase input via +terminal. It is relevant every time a passphrase is asked. +It has no effect if used in conjunction with --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. +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_REENCRYPT[] +*--tries, -T*:: +How often the input of the passphrase shall be retried. The default is 3 tries. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--align-payload *:: +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. ++ +*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. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSUUID,ACTION_REENCRYPT[] +*--uuid *:: +ifndef::ACTION_REENCRYPT[] +Use the provided _UUID_ for the _luksFormat_ command instead of +generating a new one. Changes the existing _UUID_ when used with the +_luksUUID_ command. ++ +endif::[] +ifdef::ACTION_REENCRYPT[] +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. ++ +endif::[] +The _UUID_ must be provided in the standard UUID format, e.g. +12345678-1234-1234-1234-123456789abc. +endif::[] + +ifdef::ACTION_OPEN,ACTION_REFRESH[] +*--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. +endif::[] + +ifdef::ACTION_REFRESH,ACTION_OPEN[] +*--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. ++ +*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. +endif::[] + +ifdef::ACTION_REFRESH,ACTION_OPEN[] +*--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. ++ +*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. +endif::[] + +ifdef::ACTION_REFRESH,ACTION_OPEN[] +*--perf-no_read_workqueue, --perf-no_write_workqueue*:: +Bypass dm-crypt internal workqueue and process read or write requests +synchronously. ++ +*NOTE:* These options are available only for low-level dm-crypt +performance tuning, use only if you need a change to default dm-crypt +behaviour. Needs kernel 5.9 or later. +endif::[] + +ifdef::ACTION_OPEN[] +*--test-passphrase*:: +Do not activate the device, just verify passphrase. The device mapping name is +not mandatory if this option is used. +endif::[] + +ifndef::ACTION_BENCHMARK,ACTION_BITLKDUMP[] +*--header *:: +ifndef::ACTION_OPEN[] +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. ++ +endif::[] +ifdef::ACTION_OPEN[] +Specify detached (separated) metadata device or file where the header is stored. ++ +*WARNING:* There is no check whether the ciphertext device specified +actually belongs to the header given. In fact, you can specify an +arbitrary device as the ciphertext device with the --header option. +Use with care. +endif::[] +ifndef::ACTION_REENCRYPT[] +ifdef::ACTION_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. ++ +The --align-payload option is taken as absolute sector alignment on ciphertext +device and can be zero. +endif::[] +ifndef::ACTION_LUKSFORMAT,ACTION_OPEN[] +For commands that change the LUKS header (e.g. _luksAddKey_), +specify the device or file with the LUKS header directly as the LUKS +device. +endif::[] +endif::[] +ifdef::ACTION_REENCRYPT[] +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 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 head of data +device so that data can be moved at original LUKS2 header location. Later on +decryption operation continues as if the ordinary detached header was passed. ++ +*WARNING:* Never put exported header file in a filesystem on top of device +you are about to decrypt! It would cause a deadlock. +endif::[] +endif::[] + +ifdef::ACTION_LUKSHEADERBACKUP,ACTION_LUKSHEADERRESTORE[] +*--header-backup-file *:: +Specify file with header backup file. +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--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 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. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] +*--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)*. +endif::[] + +ifdef::ACTION_CLOSE[] +*--deferred*:: +Defers device removal in _close_ command until the last user closes +it. +endif::[] + +ifdef::ACTION_CLOSE[] +*--cancel-deferred*:: +Removes a previously configured deferred device removal in _close_ +command. +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_RESIZE,ACTION_TOKEN[] +*--disable-external-tokens*:: +Disable loading of plugins for external LUKS2 tokens. +endif::[] + +ifndef::ACTION_BENCHMARK,ACTION_BITLKDUMP,ACTION_TCRYPTDUMP[] +*--disable-locks*:: +Disable lock protection for metadata on disk. This option is valid +only for LUKS2 and ignored for other formats. ++ +ifdef::ACTION_REENCRYPT[] +*NOTE:* With locking disabled LUKS2 images in files can be fully (re)encrypted +offline without need for super user privileges provided used block ciphers are +available in crypto backend. ++ +endif::[] +*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). +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_REFRESH,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_REENCRYPT[] +*--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 type. +endif::[] + +ifdef::ACTION_TOKEN[] +*--key-description *:: +Set key description in keyring for use with _token_ command. +endif::[] + +ifdef::ACTION_CONFIG[] +*--priority *:: +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. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_LUKSADDKEY[] +*--token-id*:: +ifndef::ACTION_TOKEN,ACTION_LUKSADDKEY[] +Specify what token to use and allow token PIN prompt to take precedence over interative +keyslot passphrase prompt. If omitted, all available tokens (not protected by PIN) +will be checked before proceeding further with passphrase prompt. +endif::[] +ifdef::ACTION_LUKSADDKEY[] +Specify what token to use when unlocking existing keyslot to get volume key. +endif::[] +ifdef::ACTION_TOKEN[] +Specify token number. If omitted, first unused token id is used when adding or importing +new token. +endif::[] +endif::[] + +ifdef::ACTION_LUKSADDKEY[] +*--new-token-id*:: +Specify what token to use to get the passphrase for a new keyslot. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[] +*--token-only*:: +ifndef::ACTION_LUKSADDKEY[] +Do not proceed further with action if token based keyslot unlock failed. Without the +option, action asks for passphrase to proceed further. ++ +It allows LUKS2 tokens protected by PIN to take precedence over interactive keyslot +passphrase prompt. +endif::[] +ifdef::ACTION_LUKSADDKEY[] +Use only LUKS2 tokens to unlock existing volume key. ++ +*NOTE*: To create a new keyslot using passphrase provided by a token use --new-token-id parameter. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[] +*--token-type* _type_:: +ifndef::ACTION_LUKSADDKEY[] +Restrict tokens eligible for operation to specific token _type_. +Mostly useful when no --token-id is specified. ++ +It allows LUKS2 _type_ tokens protected by PIN to take precedence over interactive keyslot +passphrase prompt. +endif::[] +ifdef::ACTION_LUKSADDKEY[] +Specify what token type (all _type_ tokens) to use when unlocking existing keyslot to get volume key. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +ifndef::ACTION_REENCRYPT[] +*--sector-size* _bytes_:: +endif::[] +ifndef::ACTION_REENCRYPT[] +ifdef::ACTION_OPEN[] +Set encryption sector size for use with _plain_ device type. It must be power of two +and in range 512 - 4096 bytes. The default mode is 512 bytes. ++ +Note that if sector size is higher than underlying device hardware +sector, using this option can increase risk on incomplete sector writes during a +power fail. +endif::[] +ifdef::ACTION_LUKSFORMAT[] +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 with LUKS2 +format. ++ +For LUKS2 devices it's established 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). +endif::[] ++ +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. +endif::[] +ifdef::ACTION_REENCRYPT[] +*--sector-size* _bytes_ *(LUKS2 only)*:: +Reencrypt device with new encryption sector size enforced. ++ +*WARNING:* Increasing encryption sector size may break hosted filesystem. Do not +run reencryption with --force-offline-reencrypt if unsure what block size +was filesystem formatted with. +endif::[] +endif::[] + +ifdef::ACTION_OPEN[] +*--iv-large-sectors*:: +Count Initialization Vector (IV) in larger sector size (if set) +instead of 512 bytes sectors. This option can be used only with _plain_ +device type. ++ +*NOTE:* This option does not have any performance or security impact, +use it only for accessing incompatible existing disk images from other +systems that require this option. +endif::[] + +ifdef::ACTION_OPEN,ACTION_REFRESH[] +*--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. +endif::[] + +ifdef::ACTION_OPEN[] +*--refresh*:: +Refreshes an active device with new set of parameters. See +*cryptsetup-refresh*(8) for more details. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_CONFIG,ACTION_REENCRYPT[] +*--label