diff --git a/.gitignore b/.gitignore index 93fc3607..db7afdee 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ Makefile.in.in *.la *.o *.so +*.8 **/*.dirstamp .deps/ .libs/ diff --git a/Makefile.am b/Makefile.am index 55994a30..c2ccb5e1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -27,6 +27,7 @@ sbin_PROGRAMS = man8_MANS = tmpfilesd_DATA = pkgconfig_DATA = +dist_noinst_DATA = include man/Makemodule.am @@ -46,7 +47,7 @@ ACLOCAL_AMFLAGS = -I m4 DISTCHECK_CONFIGURE_FLAGS = \ --with-tmpfilesdir=$$dc_install_base/usr/lib/tmpfiles.d \ --enable-internal-argon2 --enable-internal-sse-argon2 \ - --enable-external-tokens --enable-ssh-token + --enable-external-tokens --enable-ssh-token --enable-asciidoc distclean-local: -find . -name \*~ -o -name \*.orig -o -name \*.rej | xargs rm -f diff --git a/configure.ac b/configure.ac index da22368b..11aeea27 100644 --- a/configure.ac +++ b/configure.ac @@ -52,6 +52,27 @@ AS_VAR_COPY([$1], [pkg_cv_][$1]) AS_VAR_IF([$1], [""], [$5], [$4]) ]) ]) +dnl ========================================================================== +dnl AsciiDoc manual pages + +AC_ARG_ENABLE([asciidoc], + AS_HELP_STRING([--disable-asciidoc], [do not generate man pages from asciidoc]), + [], [enable_asciidoc=yes] +) + +AC_PATH_PROG([ASCIIDOCTOR], [asciidoctor]) +if test "x$enable_asciidoc" = xyes -a "x$ASCIIDOCTOR" = x; then + AC_MSG_ERROR([Building man pages requires asciidoctor installed.]) +fi +AM_CONDITIONAL([ENABLE_ASCIIDOC], [test "x$enable_asciidoc" = xyes]) + +have_manpages=no +AS_IF([test -f "$srcdir/man/cryptsetup-open.8"], [ + AC_MSG_NOTICE([re-use already generated man-pages.]) + have_manpages=yes] +) +AM_CONDITIONAL([HAVE_MANPAGES], [test "x$have_manpages" = xyes]) + dnl ========================================================================== AC_C_RESTRICT diff --git a/man/Makemodule.am b/man/Makemodule.am index f6c03b82..b4170627 100644 --- a/man/Makemodule.am +++ b/man/Makemodule.am @@ -1,16 +1,139 @@ -EXTRA_DIST += man/cryptsetup.8 man/integritysetup.8 man/veritysetup.8 man/cryptsetup-reencrypt.8 +ADOCFILES = \ + man/common_options.adoc \ + man/common_footer.adoc \ + 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-repair.8.adoc \ + man/cryptsetup-benchmark.8.adoc \ + man/cryptsetup-ssh.8.adoc \ + man/veritysetup.8.adoc \ + man/integritysetup.8.adoc -man8_MANS += man/cryptsetup.8 man/cryptsetup-reencrypt.8 +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-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-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 -man8_MANS += man/veritysetup.8 +MANPAGES += $(VERITYSETUP_MANPAGES) endif - if INTEGRITYSETUP -man8_MANS += man/integritysetup.8 +MANPAGES += $(INTEGRITYSETUP_MANPAGES) +endif +if SSHPLUGIN_TOKEN +MANPAGES += $(SSHPLUGIN_MANPAGES) endif -if SSHPLUGIN_TOKEN -EXTRA_DIST += man/cryptsetup-ssh.8 -man8_MANS += man/cryptsetup-ssh.8 +if ENABLE_ASCIIDOC +EXTRA_DIST += $(MANPAGES_ALL) +man8_MANS += $(MANPAGES) $(MANLINKS) + +SUFFIXES = .8.adoc .8 +.8.adoc.8: + $(AM_V_GEN) test -f ./$@ || \ + $(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 00000000..1ac81ed9 --- /dev/null +++ b/man/common_footer.adoc @@ -0,0 +1,16 @@ +== 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 00000000..8a14a69b --- /dev/null +++ b/man/common_options.adoc @@ -0,0 +1,1057 @@ +== 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_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_ISLUKS,ACTION_LUKSDUMP,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* __:: +ifndef::ACTION_REENCRYPT[] +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 for PBKDF2 and 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. +Do not use a non-crypto hash like *xxhash* as this breaks +security. ++ +Use _cryptsetup --help_ to show the defaults. +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::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_TCRYPTDUMP,ACTION_BENCHMARK[] +*--cipher, -c* __:: +ifndef::ACTION_REENCRYPT[] +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. +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. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--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. +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[] +*--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. ++ +ifndef::ACTION_REENCRYPT[] +With LUKS, the passphrase supplied via --key-file is always the existing +passphrase 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_ 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_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT[] +*--keyfile-offset* _value_:: +Skip _value_ bytes at the beginning of the key file. Works with all +commands that accept key files. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT[] +*--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. +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 with _luksAddKey_. +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 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. +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[] ++ +For _luksFormat_ 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[] +For _luksAddKey_ this allows adding a new passphrase without having to +know an existing one. + +endif::[] +ifdef::ACTION_OPEN[] +For _open_ this allows one to open the LUKS device 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), 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_TOKEN,ACTION_CONFIG,ACTION_TOKEN,ACTION_REENCRYPT[] +*--key-slot, -S <0-N>*:: +ifndef::ACTION_OPEN[] +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_OPEN,ACTION_LUKSFORMAT,ACTION_BENCHMARK,ACTION_REENCRYPT,ACTION_BENCHMARK,ACTION_LUKSADDKEY[] +*--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. ++ +ifndef::ACTION_REENCRYPT[] +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. +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 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]_:: +Instead of real device size, use specified value. ++ +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::[] +ifndef::ACTION_REENCRYPT[] +With _resize_ action it sets new size of the device. +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 +_open --type plain_ action. 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[] +*--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[] +*--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_RESIZE[] +*--timeout, -t *:: +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. +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,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::[] + +ifdef::ACTION_OPEN,ACTION_STATUS,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSSUSPEND,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_TOKEN,ACTION_CONVERT,ACTION_CONFIG,ACTION_REENCRYPT,ACTION_CLOSE[] +*--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. ++ +ifndef::ACTION_REENCRYPT[] +ifdef::ACTION_LUKSFORMAT[] +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. ++ +The --align-payload option is taken as absolute sector alignment on ciphertext +device and can be zero. +endif::[] +ifndef::ACTION_LUKSFORMAT[] +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 created (or overwritten). +Use with care. +endif::[] ++ +*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. ++ +*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. +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_RESIZE,ACTION_TOKEN[] +*--disable-external-tokens*:: +Disable loading of plugins for external LUKS2 tokens. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSSUSPEND,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_TOKEN,ACTION_REENCRYPT[] +*--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 +format. +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[] +*--token-id*:: +Specify what token to use. If omitted, all available tokens will be checked +before proceeding further with passphrase prompt. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME[] +*--token-only*:: +Do not proceed further with action (any of _token_, _open_, _resize_ +or _luksResume_) if token based keyslot unlock failed. Without the +option, action asks for passphrase to proceed further. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME[] +*--token-type*:: +Restrict tokens eligible for operation to specific token type (name). +Mostly useful when no --token-id is specified. +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +ifndef::ACTION_REENCRYPT[] +*--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. +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 formated 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 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. +endif::[] + +ifdef::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