Split manual pages into per-action page and use AsciiDoc format

Use pre-generated man pages in make dist.

[Added fixes and updates from Ondrej Kozina and Milan Broz]

.gitignore

@@ -7,6 +7,7 @@ Makefile.in.in
 *.la
 *.o
 *.so
+*.8
 **/*.dirstamp
 .deps/
 .libs/

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

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

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
+if ENABLE_ASCIIDOC
-EXTRA_DIST += man/cryptsetup-ssh.8
+EXTRA_DIST += $(MANPAGES_ALL)
-man8_MANS += man/cryptsetup-ssh.8
+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

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

man/cryptsetup-benchmark.8.adoc

@@ -0,0 +1,37 @@
+= cryptsetup-benchmark(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_BENCHMARK:
+
+== Name
+
+cryptsetup-benchmark - benchmarks ciphers and KDF
+
+== SYNOPSIS
+
+*cryptsetup _benchmark_ [<options>]*
+
+== DESCRIPTION
+
+Benchmarks ciphers and KDF (key derivation function). Without
+parameters, it tries to measure few common configurations.
+
+To benchmark other ciphers or modes, you need to specify *--cipher* and
+*--key-size* options or *--hash* for KDF test.
+
+*NOTE:* This benchmark uses memory only and is only informative. You
+cannot directly predict real storage encryption speed from it.
+
+For testing block ciphers, this benchmark requires kernel userspace
+crypto API to be available (introduced in Linux kernel 2.6.38). If you
+are configuring kernel yourself, enable "User-space interface for
+symmetric key cipher algorithms" in "Cryptographic API" section
+(CRYPTO_USER_API_SKCIPHER .config option).
+
+*<options>* can be [--cipher, --key-size, --hash].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-bitlkDump.8.adoc

@@ -0,0 +1,24 @@
+= cryptsetup-bitlkDump(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_BITLKDUMP:
+
+== Name
+
+cryptsetup-bitlkDump - dump the header information of a BITLK (BitLocker compatible) device
+
+== SYNOPSIS
+
+*cryptsetup _bitlkDump_ [<options>] <device>*
+
+== DESCRIPTION
+
+Dump the header information of a BITLK (BitLocker compatible) device.
+
+*<options>* can be [--dump-volume-key --volume-key-file].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-close.8.adoc

@@ -0,0 +1,30 @@
+= cryptsetup-close(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_CLOSE:
+
+== Name
+
+cryptsetup-close - removes the existing mapping <name> (and the associated key)
+
+== SYNOPSIS
+
+*cryptsetup _close_ [<options>] <name>*
+
+== DESCRIPTION
+
+Removes the existing mapping <name> and wipes the key from kernel
+memory.
+
+For backward compatibility, there are *close* command aliases: *remove*,
+*plainClose*, *luksClose*, *loopaesClose*, *tcryptClose* (all behave
+exactly the same, device type is determined automatically from the active
+device).
+
+*<options>* can be [--deferred] or [--cancel-deferred]
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-config.8.adoc

@@ -0,0 +1,30 @@
+= cryptsetup-config(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_CONFIG:
+
+== Name
+
+cryptsetup-config - set permanent configuration options (store to LUKS header)
+
+== SYNOPSIS
+
+*cryptsetup _config_ <options> <device>*
+
+== DESCRIPTION
+
+Set permanent configuration options (store to LUKS header). The _config_
+command is supported only for LUKS2.
+
+The permanent options can be _--priority_ to set priority (normal,
+prefer, ignore) for keyslot (specified by _--key-slot_) or _--label_ and
+_--subsystem_.
+
+*<options>* can be [--priority, --label, --subsystem, --key-slot,
+--header].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-convert.8.adoc

@@ -0,0 +1,37 @@
+= cryptsetup-convert(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_CONVERT:
+
+== Name
+
+cryptsetup-convert - converts the device between LUKS1 and LUKS2 format
+
+== SYNOPSIS
+
+*cryptsetup _convert_ --type <format> [<options>] <device>*
+
+== DESCRIPTION
+
+Converts the device between LUKS1 and LUKS2 format (if possible). The
+conversion will not be performed if there is an additional LUKS2 feature
+or LUKS1 has unsupported header size.
+
+Conversion (both directions) must be performed on inactive device. There
+must not be active dm-crypt mapping established for LUKS header
+requested for conversion.
+
+The *--type* option is mandatory with the following accepted values: _luks1_ or
+_luks2_.
+
+*WARNING:* The _convert_ action can destroy the LUKS header in the case
+of a crash during conversion or if a media error occurs. Always create a
+header backup before performing this operation!
+
+*<options>* can be [--header, --type].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-erase.8.adoc

@@ -0,0 +1,26 @@
+= cryptsetup-erase(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_ERASE:
+
+== Name
+
+cryptsetup-erase, cryptsetup-luksErase - erase all keyslots
+
+== SYNOPSIS
+
+*cryptsetup  _erase_ [<options>] <device>* +
+*cryptsetup _luksErase_ [<options>] <device>*
+
+== DESCRIPTION
+
+Erase all keyslots and make the LUKS container permanently inaccessible.
+You do not need to provide any password for this operation.
+
+*WARNING:* This operation is irreversible.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-isLuks.8.adoc

@@ -0,0 +1,26 @@
+= cryptsetup-isLuks(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_ISLUKS:
+
+== Name
+
+cryptsetup-isLuks - check if a device is a LUKS device
+
+== SYNOPSIS
+
+*cryptsetup _isLuks_ [<options>] <device>*
+
+== DESCRIPTION
+
+Returns true, if <device> is a LUKS device, false otherwise. Use option
+-v to get human-readable feedback. 'Command successful.' means the
+device is a LUKS device.
+
+By specifying --type you may query for specific LUKS version.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksAddKey.8.adoc

@@ -0,0 +1,40 @@
+= cryptsetup-luksAddKey(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSADDKEY:
+
+== Name
+
+cryptsetup-luksAddKey - add a new passphrase
+
+== SYNOPSIS
+
+*cryptsetup _luksAddKey_ [<options>] <device> [<key file with new key>]*
+
+== DESCRIPTION
+
+Adds a new passphrase. An existing passphrase must be supplied
+interactively or via --key-file. The new passphrase to be added can be
+specified interactively or read from the file given as the positional
+argument.
+
+*NOTE:* with --unbound option the action creates new unbound LUKS2
+keyslot. The keyslot cannot be used for device activation. If you don't
+pass new key via --volume-key-file option, new random key is generated.
+Existing passphrase for any active keyslot is not required.
+
+*NOTE:* some parameters are effective only if used with LUKS2 format
+that supports per-keyslot parameters. For LUKS1, PBKDF type and hash
+algorithm is always the same for all keyslots.
+
+*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
+--new-keyfile-offset, --new-keyfile-size, --key-slot, --volume-key-file,
+--force-password, --hash, --header, --disable-locks, --iter-time,
+--pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel,
+--unbound, --type, --keyslot-cipher, --keyslot-key-size].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksChangeKey.8.adoc

@@ -0,0 +1,46 @@
+= cryptsetup-luksChangeKey(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSCHANGEKEY:
+
+== Name
+
+cryptsetup-luksChangeKey - change an existing passphrase
+
+== SYNOPSIS
+
+*cryptsetup _luksChangeKey_ [<options>] <device> [<new key file>]*
+
+== DESCRIPTION
+
+Changes an existing passphrase. The passphrase to be changed must be
+supplied interactively or via --key-file. The new passphrase can be
+supplied interactively or in a file given as the positional argument.
+
+If a key-slot is specified (via --key-slot), the passphrase for that
+key-slot must be given and the new passphrase will overwrite the
+specified key-slot. If no key-slot is specified and there is still a
+free key-slot, then the new passphrase will be put into a free key-slot
+before the key-slot containing the old passphrase is purged. If there is
+no free key-slot, then the key-slot with the old passphrase is
+overwritten directly.
+
+*WARNING:* If a key-slot is overwritten, a media failure during this
+operation can cause the overwrite to fail after the old passphrase has
+been wiped and make the LUKS container inaccessible.
+
+*NOTE:* some parameters are effective only if used with LUKS2 format
+that supports per-keyslot parameters. For LUKS1, PBKDF type and hash
+algorithm is always the same for all keyslots.
+
+*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
+--new-keyfile-offset, --iter-time, --pbkdf, --pbkdf-force-iterations,
+--pbkdf-memory, --pbkdf-parallel, --new-keyfile-size, --key-slot,
+--force-password, --hash, --header, --disable-locks, --type,
+--keyslot-cipher, --keyslot-key-size].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksConvertKey.8.adoc

@@ -0,0 +1,41 @@
+= cryptsetup-luksConvertKey(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSCONVERTKEY:
+
+== Name
+
+cryptsetup-luksConvertKey - converts an existing LUKS2 keyslot to new PBKDF parameters
+
+== SYNOPSIS
+
+*cryptsetup _luksConvertKey_ [<options>] <device>*
+
+== DESCRIPTION
+
+Converts an existing LUKS2 keyslot to new PBKDF parameters. The
+passphrase for keyslot to be converted must be supplied interactively or
+via --key-file. If no --pbkdf parameters are specified LUKS2 default
+PBKDF values will apply.
+
+If a keyslot is specified (via --key-slot), the passphrase for that
+keyslot must be given. If no keyslot is specified and there is still a
+free keyslot, then the new parameters will be put into a free keyslot
+before the keyslot containing the old parameters is purged. If there is
+no free keyslot, then the keyslot with the old parameters is overwritten
+directly.
+
+*WARNING:* If a keyslot is overwritten, a media failure during this
+operation can cause the overwrite to fail after the old parameters have
+been wiped and make the LUKS container inaccessible.
+
+*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
+--key-slot, --hash, --header, --disable-locks, --iter-time, --pbkdf,
+--pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel,
+--keyslot-cipher, --keyslot-key-size].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksDump.8.adoc

@@ -0,0 +1,50 @@
+= cryptsetup-luksDump(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSDUMP:
+
+== Name
+
+cryptsetup-luksDump - dump the header information of a LUKS device
+
+== SYNOPSIS
+
+*cryptsetup _luksDump_ [<options>] <device>*
+
+== DESCRIPTION
+
+Dump the header information of a LUKS device.
+
+If the --dump-volume-key option is used, the LUKS device volume key is
+dumped instead of the keyslot info. Together with the --volume-key-file
+option, volume key is dumped to a file instead of standard output.
+Beware that the volume key cannot be changed without reencryption and
+can be used to decrypt the data stored in the LUKS container without a
+passphrase and even without the LUKS header. This means that if the
+volume key is compromised, the whole device has to be erased or
+reencrypted to prevent further access. Use this option carefully.
+
+To dump the volume key, a passphrase has to be supplied, either
+interactively or via --key-file.
+
+To dump unbound key (LUKS2 format only), --unbound parameter, specific
+--key-slot id and proper passphrase has to be supplied, either
+interactively or via --key-file. Optional --volume-key-file parameter
+enables unbound keyslot dump to a file.
+
+To dump LUKS2 JSON metadata (without basic heade information like UUID)
+use --dump-json-metadata option.
+
+*<options>* can be [--dump-volume-key, --dump-json-metadata, --key-file,
+--keyfile-offset, --keyfile-size, --header, --disable-locks,
+--volume-key-file, --type, --unbound, --key-slot].
+
+*WARNING:* If --dump-volume-key is used with --key-file and the argument
+to --key-file is '-', no validation question will be asked and no
+warning given.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksFormat.8.adoc

@@ -0,0 +1,50 @@
+= cryptsetup-luksFormat(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSFORMAT:
+
+== Name
+
+cryptsetup-luksFormat - initialize a LUKS partition and set the initial passphrase
+
+== SYNOPSIS
+
+*cryptsetup _luksFormat_ [<options>] <device> [<key file>]*
+
+== DESCRIPTION
+
+Initializes a LUKS partition and sets the initial passphrase (for
+key-slot 0), either via prompting or via <key file>. Note that if the
+second argument is present, then the passphrase is taken from the file
+given there, without the need to use the --key-file option. Also note
+that for both forms of reading the passphrase from a file you can give
+'-' as file name, which results in the passphrase being read from stdin
+and the safety-question being skipped.
+
+You cannot call luksFormat on a device or filesystem that is mapped or
+in use, e.g., mounted filesystem, 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 _--type luks2_.
+
+*<options>* can be [--hash, --cipher, --verify-passphrase, --key-size,
+--key-slot, --key-file (takes precedence over optional second argument),
+--keyfile-offset, --keyfile-size, --use-random | --use-urandom, --uuid,
+--volume-key-file, --iter-time, --header, --pbkdf-force-iterations,
+--force-password, --disable-locks].
+
+For LUKS2, additional *<options>* can be [--integrity,
+--integrity-no-wipe, --sector-size, --label, --subsystem, --pbkdf,
+--pbkdf-memory, --pbkdf-parallel, --disable-locks, --disable-keyring,
+--luks2-metadata-size, --luks2-keyslots-size, --keyslot-cipher,
+--keyslot-key-size].
+
+*WARNING:* Doing a luksFormat on an existing LUKS container will make
+all data in the old container permanently irretrievable unless you have a
+header backup.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksHeaderBackup.8.adoc

@@ -0,0 +1,33 @@
+= cryptsetup-luksHeaderBackup(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSHEADERBACKUP:
+
+== Name
+
+cryptsetup-luksHeaderBackup - store a binary backup of the LUKS header and keyslot area
+
+== SYNOPSIS
+
+*cryptsetup _luksHeaderBackup_ --header-backup-file <file> [<options>] <device>*
+
+== DESCRIPTION
+
+Stores a binary backup of the LUKS header and keyslot area. +
+Note: Using '-' as filename writes the header backup to a file named
+'-'.
+
+*WARNING:* This backup file and a passphrase valid at the time of backup
+allows decryption of the LUKS data area, even if the passphrase was
+later changed or removed from the LUKS device. Also note that with a
+header backup you lose the ability to securely wipe the LUKS device by
+just overwriting the header and key-slots. You either need to securely
+erase all header backups in addition or overwrite the encrypted data
+area as well. The second option is less secure, as some sectors can
+survive, e.g., due to defect management.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksHeaderRestore.8.adoc

@@ -0,0 +1,33 @@
+= cryptsetup-luksHeaderRestore(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSHEADERRESTORE:
+
+== Name
+
+cryptsetup-luksHeaderRestore - restore a binary backup of the LUKS header and keyslot area
+
+== SYNOPSIS
+
+*cryptsetup _luksHeaderRestore_ --header-backup-file <file> [<options>] <device>*
+
+== DESCRIPTION
+
+Restores a binary backup of the LUKS header and keyslot area from the
+specified file. +
+Note: Using '-' as filename reads the header backup from a file named
+'-'.
+
+*WARNING:* Header and keyslots will be replaced, only the passphrases
+from the backup will work afterward.
+
+This command requires that the volume key size and data offset of the
+LUKS header already on the device and of the header backup match.
+Alternatively, if there is no LUKS header on the device, the backup will
+also be written to it.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksKillSlot.8.adoc

@@ -0,0 +1,40 @@
+= cryptsetup-luksKillSlot(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSKILLSLOT:
+
+== Name
+
+cryptsetup-luksKillSlot - wipe a key-slot from the LUKS device
+
+== SYNOPSIS
+
+*cryptsetup _luksKillSlot_ [<options>] <device> <key slot number>*
+
+== DESCRIPTION
+
+Wipe the key-slot number <key slot> from the LUKS device. Except running
+in batch-mode (-q) a remaining passphrase must be supplied, either
+interactively or via --key-file. This command can remove the last
+remaining key-slot, but requires an interactive confirmation when doing
+so. Removing the last passphrase makes a LUKS container permanently
+inaccessible.
+
+*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
+--header, --disable-locks, --type].
+
+*WARNING:* If you read the passphrase from stdin (without further
+argument or with '-' as an argument to --key-file), batch-mode (-q) will
+be implicitly switched on and no warning will be given when you remove
+the last remaining passphrase from a LUKS container. Removing the last
+passphrase makes the LUKS container permanently inaccessible.
+
+*NOTE:* If there is no passphrase provided (on stdin or through
+--key-file argument) and batch-mode (-q) is active, the key-slot is
+removed without any other warning.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksRemoveKey.8.adoc

@@ -0,0 +1,33 @@
+= cryptsetup-luksRemoveKey(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSREMOVEKEY:
+
+== Name
+
+cryptsetup-luksRemoveKey - remove the supplied passphrase from the LUKS device
+
+== SYNOPSIS
+
+*cryptsetup _luksRemoveKey_ [<options>] <device> [<key file with passphrase to be removed>]*
+
+== DESCRIPTION
+
+Removes the supplied passphrase from the LUKS device. The passphrase to
+be removed can be specified interactively, as the positional argument or
+via --key-file.
+
+*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
+--header, --disable-locks, --type]
+
+*WARNING:* If you read the passphrase from stdin (without further
+argument or with '-' as an argument to --key-file), batch-mode (-q) will
+be implicitly switched on and no warning will be given when you remove
+the last remaining passphrase from a LUKS container. Removing the last
+passphrase makes the LUKS container permanently inaccessible.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksResume.8.adoc

@@ -0,0 +1,28 @@
+= cryptsetup-luksResume(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSRESUME:
+
+== Name
+
+cryptsetup-luksResume - resume a suspended device and reinstate the key
+
+== SYNOPSIS
+
+*cryptsetup _luksResume_ [<options>] <name>*
+
+== DESCRIPTION
+
+Resumes a suspended device and reinstates the encryption key. Prompts
+interactively for a passphrase if no token is usable (LUKS2 only) or
+--key-file is not given.
+
+*<options>* can be [--key-file, --keyfile-size, --header,
+--disable-keyring, --disable-locks, --token-id, --token-only,
+--token-type, --type]
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksSuspend.8.adoc

@@ -0,0 +1,33 @@
+= cryptsetup-luksSuspend(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSSUSPEND:
+
+== Name
+
+cryptsetup-luksSuspend - suspends an active device and wipes the key
+
+== SYNOPSIS
+
+*cryptsetup _luksSuspend_ [<options>] <name>*
+
+== DESCRIPTION
+
+Suspends an active device (all IO operations will block and accesses to
+the device will wait indefinitely) and wipes the encryption key from
+kernel memory. Needs kernel 2.6.19 or later.
+
+After this operation, you have to use _luksResume_ to reinstate the
+encryption key and unblock the device or _close_ to remove the mapped
+device.
+
+*WARNING:* Never suspend the device on which the cryptsetup binary
+resides.
+
+*<options>* can be [--header, --disable-locks].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-luksUUID.8.adoc

@@ -0,0 +1,23 @@
+= cryptsetup-luksUUID(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_LUKSUUID:
+
+== Name
+
+cryptsetup-luksUUID - print or set the UUID of a LUKS device
+
+== SYNOPSIS
+
+*cryptsetup _luksUUID_ [<options>] <device>*
+
+== DESCRIPTION
+
+Print the UUID of a LUKS device. +
+Set new UUID if _--uuid_ option is specified.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-open.8.adoc

@@ -0,0 +1,144 @@
+= cryptsetup-open(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_OPEN:
+
+== Name
+
+cryptsetup-open, cryptsetup-create, cryptsetup-plainOpen, cryptsetup-luksOpen, cryptsetup-loopaesOpen, cryptsetup-tcryptOpen, cryptsetup-bitlkOpen - open an encrypted device and create a mapping with a specified name
+
+== SYNOPSIS
+
+*cryptsetup _open_ --type <device_type> [<options>] <device> <name>*
+
+== DESCRIPTION
+Opens (creates a mapping with) <name> backed by device <device>.
+
+Device type can be _plain_, _luks_ (default), _luks1_, _luks2_,
+_loopaes_ or _tcrypt_.
+
+For backward compatibility there are *open* command aliases:
+
+*create* (argument-order <name> <device>): open --type plain +
+*plainOpen*: open --type plain +
+*luksOpen*: open --type luks +
+*loopaesOpen*: open --type loopaes +
+*tcryptOpen*: open --type tcrypt +
+*bitlkOpen*: open --type bitlk
+
+*<options>* are type specific and are described below for individual
+device types. For *create*, the order of the <name> and <device> options
+is inverted for historical reasons, all other aliases use the standard
+*<device> <name>* order.
+
+=== PLAIN
+*open --type plain <device> <name>* +
+plainOpen <device> <name> (*old syntax*) +
+create <name> <device> (*OBSOLETE syntax*)
+
+Opens (creates a mapping with) <name> backed by device <device>.
+
+*<options>* can be [--hash, --cipher, --verify-passphrase,
+--sector-size, --key-file, --keyfile-offset, --key-size, --offset,
+--skip, --device-size, --size, --readonly, --shared, --allow-discards,
+--refresh]
+
+Example: 'cryptsetup open --type plain /dev/sda10 e1' maps the raw
+encrypted device /dev/sda10 to the mapped (decrypted) device
+/dev/mapper/e1, which can then be mounted, fsck-ed or have a filesystem
+created on it.
+
+=== LUKS
+*open --type luks <device> <name>* +
+luksOpen <device> <name> (*old syntax*)
+
+Opens the LUKS device <device> and sets up a mapping <name> after
+successful verification of the supplied passphrase.
+
+First, the passphrase is searched in LUKS tokens. If it's not found in
+any token and also the passphrase is not supplied via --key-file, the
+command prompts for it interactively.
+
+*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
+--readonly, --test-passphrase, --allow-discards, --header, --key-slot,
+--volume-key-file, --token-id, --token-only, --token-type,
+--disable-external-tokens, --disable-keyring, --disable-locks, --type,
+--refresh, --serialize-memory-hard-pbkdf, --unbound].
+
+=== loopAES
+*open --type loopaes <device> <name> --key-file <keyfile>* +
+loopaesOpen <device> <name> --key-file <keyfile> (*old syntax*)
+
+Opens the loop-AES <device> and sets up a mapping <name>.
+
+If the key file is encrypted with GnuPG, then you have to use
+--key-file=- and decrypt it before use, e.g., like this: +
+gpg --decrypt <keyfile> | cryptsetup loopaesOpen --key-file=- <device>
+<name>
+
+*WARNING:* The loop-AES extension cannot use the direct input of the key
+file on the real terminal because the keys are separated by end-of-line and
+only part of the multi-key file would be read. +
+If you need it in script, just use the pipe redirection: +
+echo $keyfile | cryptsetup loopaesOpen --key-file=- <device> <name>
+
+Use *--keyfile-size* to specify the proper key length if needed.
+
+Use *--offset* to specify device offset. Note that the units need to be
+specified in number of 512 byte sectors.
+
+Use *--skip* to specify the IV offset. If the original device used an
+offset and but did not use it in IV sector calculations, you have to
+explicitly use *--skip 0* in addition to the offset parameter.
+
+Use *--hash* to override the default hash function for passphrase
+hashing (otherwise it is detected according to key size).
+
+*<options>* can be [--key-file, --key-size, --offset, --skip, --hash,
+--readonly, --allow-discards, --refresh].
+
+=== TrueCrypt and VeraCrypt
+*open --type tcrypt <device> <name>* +
+tcryptOpen <device> <name> (*old syntax*)
+
+Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) <device> and sets
+up a mapping <name>.
+
+*<options>* can be [--key-file, --tcrypt-hidden, --tcrypt-system,
+--tcrypt-backup, --readonly, --test-passphrase, --allow-discards,
+--disable-veracrypt, --veracrypt-pim, --veracrypt-query-pim, --header,
+--cipher, --hash].
+
+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 *--cipher* or *--hash* options are used, only cipher chains or PBKDF2
+variants with the specified hash algorithms are checked. This could
+speed up unlocking the device (but also it reveals some information
+about the container).
+
+If you use *--header* in combination with hidden or system options, the
+header file must contain specific headers on the same positions as the
+original encrypted container.
+
+*WARNING:* Option *--allow-discards* cannot be combined with option
+*--tcrypt-hidden*. For normal mapping, it can cause the *destruction of
+hidden volume* (hidden volume appears as unused space for outer volume
+so this space can be discarded).
+
+=== BitLocker
+*open --type bitlk <device> <name>* +
+bitlkOpen <device> <name> (*old syntax*)
+
+Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping
+<name>.
+
+*<options>* can be [--key-file, --readonly, --test-passphrase,
+--allow-discards --volume-key-file].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-reencrypt.8

@@ -1,295 +0,0 @@
-.TH CRYPTSETUP-REENCRYPT "8" "January 2021" "cryptsetup-reencrypt" "Maintenance Commands"
-.SH NAME
-cryptsetup-reencrypt - tool for offline LUKS device re-encryption
-.SH SYNOPSIS
-.B cryptsetup-reencrypt <options> <device>
-.SH DESCRIPTION
-.PP
-Cryptsetup-reencrypt can be used to change reencryption parameters
-which otherwise require full on-disk data change (re-encryption).
-
-You can regenerate \fBvolume key\fR (the real key used in on-disk encryption
-unclocked by passphrase), \fBcipher\fR, \fBcipher mode\fR.
-
-Cryptsetup-reencrypt reencrypts data on LUKS device in-place. During
-reencryption process the LUKS device is marked unavailable.
-
-\fINOTE\fR: If you're looking for LUKS2 online reencryption manual please read cryptsetup(8)
-man page instead (see reencrypt action). This page is for legacy offline reencryption
-utility only.
-
-\fIWARNING\fR: The cryptsetup-reencrypt program is not resistant to hardware
-or kernel failures during reencryption (you can lose your data in this case).
-
-\fIALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL.\fR
-.br
-The reencryption can be temporarily suspended (by TERM signal or by
-using ctrl+c) but you need to retain temporary files named LUKS-<uuid>.[log|org|new].
-LUKS device is unavailable until reencryption is finished though.
-
-Current working directory must be writable and temporary
-files created during reencryption must be present.
-
-For more info about LUKS see cryptsetup(8).
-.PP
-.SH OPTIONS
-.TP
-To start (or continue) re-encryption for <device> use:
-.PP
-\fIcryptsetup-reencrypt\fR <device>
-
-\fB<options>\fR can be [\-\-batch-mode, \-\-block-size, \-\-cipher | \-\-keep-key,
-\-\-debug, \-\-device-size, \-\-hash, \-\-header, \-\-iter-time | \-\-pbkdf\-force\-iterations,
-\-\-key-file, \-\-key-size, \-\-key-slot, \-\-keyfile-offset, \-\-keyfile-size,
-\-\-volume\-key\-file, \-\-tries, \-\-pbkdf, \-\-pbkdf\-memory, \-\-pbkdf\-parallel,
-\-\-progress-frequency, \-\-use-directio, \-\-use-random | \-\-use-urandom, \-\-use-fsync,
-\-\-uuid, \-\-verbose, \-\-write-log]
-
-To encrypt data on (not yet encrypted) device, use \fI\-\-new\fR in combination
-with \fI\-\-reduce-device-size\fR or with \fI\-\-header\fR option for detached header.
-
-To remove encryption from device, use \fI\-\-decrypt\fR.
-
-For detailed description of encryption and key file options see \fIcryptsetup(8)\fR
-man page.
-.TP
-.B "\-\-batch-mode, \-q"
-Suppresses all warnings and reencryption progress output.
-.TP
-.B "\-\-block-size, \-B \fIvalue\fR"
-Use re-encryption block size of <value> in MiB.
-
-Values can be between 1 and 64 MiB.
-.TP
-.B "\-\-cipher, \-c" \fI<cipher-spec>\fR
-Set the cipher specification string.
-.TP
-.B "\-\-debug"
-Run in debug mode with full diagnostic logs. Debug output
-lines are always prefixed by '#'.
-.TP
-.B "\-\-decrypt"
-Remove encryption (decrypt already encrypted device and remove LUKS header).
-
-\fBWARNING:\fR This is destructive operation and cannot be reverted.
-.TP
-.B "\-\-device-size \fIsize[units]\fR"
-Instead of real device size, use specified value.
-
-It means that only specified area (from the start of the device
-to the specified size) will be reencrypted.
-
-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).
-
-\fBWARNING:\fR This is destructive operation.
-.TP
-.B "\-\-hash, \-h \fI<hash-spec>\fR"
-Specifies the hash used in the LUKS1 key setup scheme and volume key digest.
-
-\fBNOTE:\fR if this parameter is not specified, default hash algorithm is always used
-for new LUKS1 device header.
-
-\fBNOTE:\fR with LUKS2 format this option is only relevant when new keyslot pbkdf algorithm
-is set to PBKDF2 (see \fI\-\-pbkdf\fR).
-.TP
-.B "\-\-header\fR \fI<LUKS header file>\fR"
-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.
-
-\fBWARNING:\fR There is no check whether the ciphertext device specified
-actually belongs to the header given.
-If used with \fI\-\-new\fR option, the header file will created (or overwritten).
-Use with care.
-.TP
-.B "\-\-iter-time, \-i \fI<milliseconds>\fR"
-The number of milliseconds to spend with PBKDF2 passphrase processing for the
-new LUKS header.
-.TP
-.B "\-\-keep-key"
-Do not change encryption key, just reencrypt the LUKS header and keyslots.
-
-This option can be combined only with \fI\-\-hash\fR, \fI\-\-iter-time\fR,
-\fI\-\-pbkdf\-force\-iterations\fR, \fI\-\-pbkdf\fR (LUKS2 only),
-\fI\-\-pbkdf\-memory\fR (Argon2i/id and LUKS2 only) and \fI\-\-pbkdf\-parallel\fR
-(Argon2i/id and LUKS2 only) options.
-.TP
-.B "\-\-key-file, \-d \fIname\fR"
-Read the passphrase from file.
-
-\fBWARNING:\fR \-\-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-reencrypt will ask for all active keyslot
-passphrases.
-.TP
-.B "\-\-key-size, \-s \fI<bits>\fR"
-Set 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.
-
-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.
-.TP
-.B "\-\-key-slot, \-S <0-MAX>"
-Specify which key slot is used. For LUKS1, max keyslot number is 7. For LUKS2, it's 31.
-
-\fBWARNING:\fR All other keyslots will be disabled if this option is used.
-.TP
-.B "\-\-keyfile-offset \fIvalue\fR"
-Skip \fIvalue\fR bytes at the beginning of the key file.
-.TP
-.B "\-\-keyfile-size, \-l"
-Read a maximum of \fIvalue\fR bytes from the key file.
-Default is to read the whole file up to the compiled-in
-maximum.
-.TP
-.B "\-\-volume\-key\-file, \-\-master\-key\-file (OBSOLETE alias)"
-Use new volume key stored in a file.
-.TP
-.B "\-\-new, \-N"
-Create new header (encrypt not yet encrypted device).
-
-This option must be used together with \-\-reduce-device-size.
-
-\fBWARNING:\fR This is destructive operation and cannot be reverted.
-.TP
-.B "\-\-pbkdf"
-Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot.
-The PBKDF can be: \fIpbkdf2\fR, \fIargon2i\fR for Argon2i or \fIargon2id\fR for Argon2id.
-
-For LUKS1, only \fIpbkdf2\fR is accepted (no need to use this option).
-.TP
-.B "\-\-pbkdf\-force\-iterations <num>"
-Avoid PBKDF benchmark and set time cost (iterations) directly.
-.TP
-.B "\-\-pbkdf\-memory <number>"
-Set the memory cost for PBKDF (for Argon2i/id the number represents kilobytes).
-Note that it is maximal value, PBKDF benchmark or available physical memory
-can decrease it.
-This option is not available for PBKDF2.
-.TP
-.B "\-\-pbkdf\-parallel <number>"
-Set the parallel cost for PBKDF (number of threads, up to 4).
-Note that it is maximal value, it is decreased automatically if
-CPU online count is lower.
-This option is not available for PBKDF2.
-.TP
-.B "\-\-progress-frequency <seconds>"
-Print separate line every <seconds> with reencryption progress.
-.TP
-.B "\-\-reduce-device-size \fIsize[units]\fR"
-Enlarge data offset to specified value by shrinking device size.
-
-This means that last sectors on the original device will be lost,
-ciphertext data will be effectively shifted by specified
-number of sectors.
-
-It can be useful if you e.g. added some space to underlying
-partition (so last sectors contains no data).
-
-For units suffix see \-\-device-size parameter description.
-
-You cannot shrink device more than by 64 MiB (131072 sectors).
-
-\fBWARNING:\fR This is destructive operation and cannot be reverted.
-Use with extreme care - shrunk filesystems are usually unrecoverable.
-.TP
-.B "\-\-tries, \-T"
-Number of retries for invalid passphrase entry.
-.TP
-.B "\-\-type <type>"
-Use only while encrypting not yet encrypted device (see \-\-new).
-
-Specify LUKS version when performing in-place encryption. If the parameter
-is omitted default value (LUKS1) is used. Type may be one of: \fBluks\fR (default),
-\fBluks1\fR or \fBluks2\fR.
-.TP
-.B "\-\-use-directio"
-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).
-.TP
-.B "\-\-use-fsync"
-Use fsync call after every written block. This applies for reencryption
-log files as well.
-.TP
-.B "\-\-use-random"
-.TP
-.B "\-\-use-urandom"
-Define which kernel random number generator will be used to create the volume key.
-.TP
-.B "\-\-uuid" \fI<uuid>\fR
-Use only while resuming an interrupted decryption process (see \-\-decrypt).
-
-To find out what \fI<uuid>\fR to pass look for temporary files LUKS-<uuid>.[|log|org|new]
-of the interrupted decryption process.
-.TP
-.B "\-\-verbose, \-v"
-Print more information on command execution.
-.TP
-.B "\-\-version"
-Show the program version.
-.TP
-.B "\-\-write-log"
-Update log file after every block write. This can slow down reencryption
-but will minimize data loss in the case of system crash.
-
-.SH RETURN CODES
-Cryptsetup-reencrypt returns 0 on success and a non-zero value on error.
-
-Error codes are: 1 wrong parameters, 2 no permission,
-3 out of memory, 4 wrong device specified, 5 device already exists
-or device is busy.
-.SH EXAMPLES
-.TP
-Reencrypt /dev/sdb1 (change volume key)
-cryptsetup-reencrypt /dev/sdb1
-.TP
-Reencrypt and also change cipher and cipher mode
-cryptsetup-reencrypt /dev/sdb1 \-c aes-xts-plain64
-.TP
-Add LUKS encryption to not yet encrypted device
-
-First, be sure you have space added to disk.
-
-Or alternatively shrink filesystem in advance.
-.br
-Here we need 4096 512-bytes sectors (enough for 2x128 bit key).
-
-fdisk \-u /dev/sdb # move sdb1 partition end + 4096 sectors
-(or use resize2fs or tool for your filesystem and shrink it)
-
-cryptsetup-reencrypt /dev/sdb1 \-\-new \-\-reduce-device-size 4096S
-.TP
-Remove LUKS encryption completely
-
-cryptsetup-reencrypt /dev/sdb1 \-\-decrypt
-
-.SH REPORTING BUGS
-Report bugs, including ones in the documentation, on
-the cryptsetup mailing list at <cryptsetup@lists.linux.dev>
-or in the 'Issues' section on LUKS website.
-Please attach the output of the failed command with the
-\-\-debug option added.
-.SH AUTHORS
-Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>.
-.SH COPYRIGHT
-Copyright \(co 2012-2022 Milan Broz
-.br
-Copyright \(co 2012-2022 Red Hat, Inc.
-
-This is free software; see the source for copying conditions.  There is NO
-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-.SH SEE ALSO
-The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR

man/cryptsetup-reencrypt.8.adoc

@@ -0,0 +1,173 @@
+= cryptsetup-reencrypt(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_REENCRYPT:
+
+== Name
+
+cryptsetup-reencrypt - reencrypt LUKS encrypted volumes in-place
+
+== SYNOPSIS
+
+*cryptsetup _reencrypt_ [<options>] <device> or --active-name <name> [<new_name>]*
+
+== DESCRIPTION
+
+Run LUKS device reencryption.
+
+There are 3 basic modes of operation:
+
+* device reencryption (_reencrypt_)
+* device encryption (_reencrypt_ --encrypt/--new/-N)
+* device decryption (_reencrypt_ --decrypt)
+
+<device> or --active-name <name> (LUKS2 only) is mandatory parameter.
+
+Cryptsetup _reencrypt_ action can be used to change reencryption parameters
+which otherwise require full on-disk data change (re-encryption). The
+_reencrypt_ action reencrypts data on LUKS device in-place.
+
+You can regenerate *volume key* (the real key used in on-disk encryption
+unclocked by passphrase), *cipher*, *cipher mode* or *encryption sector size*
+(LUKS2 only).
+
+Reencryption process may be safely interrupted by a user via SIGINT
+signal (ctrl+c). Same applies to SIGTERM signal (i.e. issued by systemd
+during system shutdown).
+
+For in-place encryption mode, the _reencrypt_ action aditionally takes all
+options available for _luksFormat_ action for respective LUKS version (see
+cryptsetup-luksFormat man page for more details). See *cryptsetup-luksFormat*(8).
+
+*NOTE* that for encrypt and decrypt mode, the whole device must be
+treated as unencrypted -- there are no quarantees of confidentiality as
+part of the device contains plaintext.
+
+*ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS ACTION ON LUKS DEVICE.*
+
+*<options>* can be [--batch-mode,
+--block-size,
+--cipher,
+--debug,
+--debug-json,
+--decrypt,
+--device-size,
+--encrypt,
+--force-offline-reencrypt,
+--hash,
+--header,
+--hotzone-size,
+--iter-time,
+--init-only,
+--keep-key,
+--key-file,
+--key-size,
+--key-slot,
+--keyfile-offset,
+--keyfile-size,
+--tries,
+--pbkdf,
+--pbkdf-force-iterations,
+--pbkdf-memory,
+--pbkdf-parallel,
+--progress-frequency,
+--progress-json,
+--reduce-device-size,
+--resilience,
+--resilience-hash,
+--resume-only,
+--sector-size,
+--use-directio,
+--use-random,
+--use-urandom,
+--use-fsync,
+--uuid,
+--verbose,
+--volume-key-file,
+--write-log]
+
+== LUKS2 REENCRYPTION
+
+With <device> parameter cryptsetup looks up active <device> dm mapping.
+If no active mapping is detected, it starts offline LUKS2 reencryption
+otherwise online reencryption takes place.
+
+To resume already initialized or interrupted reencryption, just run the
+cryptsetup _reencrypt_ command again to continue the reencryption
+operation. Reencryption may be resumed with different --resilience or
+--hotzone-size unless implicit datashift resilience mode is used: either
+encrypt mode with --reduce-device-size option or decrypt mode with
+original LUKS2 header exported in --header file.
+
+If the reencryption process was interrupted abruptly (reencryption
+process crash, system crash, poweroff) it may require recovery. The
+recovery is currently run automatically on next activation (action
+_open_) when needed or explicitly by user (action _repair_).
+
+Optional parameter <new_name> takes effect only with encrypt option
+and it activates device <new_name> immediately after encryption
+initialization gets finished. That's useful when device needs to be
+ready as soon as possible and mounted (used) before full data area
+encryption is completed.
+
+== LUKS1 REENCRYPTION
+
+Current working directory must be writable and temporary files created during
+reencryption must be present. During reencryption process the LUKS1 device is
+marked unavailable and must be offline (no dm-crypt mapping or mounted
+filesystem).
+
+*WARNING*: The LUKS1 reencryption code is not resistant to hardware
+or kernel failures during reencryption (you can lose your data in this case).
+
+include::man/common_options.adoc[]
+
+== EXAMPLES
+
+*NOTE*: You may drop *--type luks2* option as long as LUKS2 format is
+default.
+
+=== LUKS2 ENCRYPTION EXAMPLES
+
+Encrypt LUKS2 device (in-place). Make sure last 32 MiB on _/dev/plaintext_
+is unused (e.g.: does not contain filesystem data):
+
+*cryptsetup reencrypt --encrypt --type luks2 --reduce-device-size 32m /dev/plaintext_device*
+
+Encrypt LUKS2 device (in-place) with detached header put in a file:
+
+*cryptsetup reencrypt --encrypt --type luks2 --header my_luks2_header /dev/plaintext_device*
+
+Initalize LUKS2 in-place encryption operation only and activate the device (not yet encrypted):
+
+*cryptsetup reencrypt --encrypt --type luks2 --init-only --reduce-device-size 32m /dev/plaintext_device my_future_luks_device*
+
+Resume online encryption on device initialized in example above:
+
+*cryptsetup reencrypt --resume-only /dev/plaintext_device* or
+*cryptsetup reencrypt --active-name my_future_luks_device*
+
+=== LUKS2 REENCRYPTION EXAMPLES
+
+Reencrypt LUKS2 device (refresh volume key only):
+
+*cryptsetup reencrypt /dev/encrypted_device*
+
+=== LUKS2 DECRYPTION EXAMPLES
+
+Decrypt LUKS2 device with header put in head of data device (header file does not exist):
+
+*cryptsetup reencrypt --decrypt --header /export/header/to/file /dev/encrypted_device*
+
+Decrypt LUKS2 device with detached header (header file exists):
+
+*cryptsetup reencrypt --decrypt --header detached-luks2-header /dev/encrypted_device*
+
+Resume interrupted LUKS2 decryption:
+
+*cryptsetup reencrypt --resume-only --header luks2-hdr-file /dev/encrypted_device*
+
+include::man/common_footer.adoc[]

man/cryptsetup-refresh.8.adoc

@@ -0,0 +1,49 @@
+= cryptsetup-refresh(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_REFRESH:
+
+== Name
+
+cryptsetup-refresh - refresh parameters of an active mapping
+
+== SYNOPSIS
+
+*cryptsetup _refresh_ [<options>] <name>*
+
+== DESCRIPTION
+
+Refreshes parameters of active mapping <name>.
+
+Updates parameters of active device <name> without the need to deactivate
+the device (and umount filesystem). Currently, it supports parameters
+refresh on following devices: LUKS1, LUKS2 (including authenticated
+encryption), plain crypt and loop-AES.
+
+Mandatory parameters are identical to those of an open action for
+the respective device type.
+
+You may change following parameters on all devices
+--perf-same_cpu_crypt, --perf-submit_from_crypt_cpus,
+--perf-no_read_workqueue, --perf-no_write_workqueue and
+--allow-discards.
+
+Refreshing the device without any optional parameter will refresh the device
+with default setting (respective to device type).
+
+*LUKS2 only:*
+
+The --integrity-no-journal parameter affects only LUKS2 devices with
+the underlying dm-integrity device.
+
+Adding option --persistent stores any combination of device parameters
+above in LUKS2 metadata (only after successful refresh operation).
+
+The --disable-keyring parameter refreshes a device with volume key passed in
+dm-crypt driver.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-repair.8.adoc

@@ -0,0 +1,38 @@
+= cryptsetup-repair(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_REPAIR:
+
+== Name
+
+cryptsetup-repair - repair the device metadata
+
+== SYNOPSIS
+
+*cryptsetup _repair_ [<options>] <device>*
+
+== DESCRIPTION
+
+Tries to repair the device metadata if possible. Currently supported
+only for LUKS device type.
+
+This command is useful to fix some known benign LUKS metadata header
+corruptions. Only basic corruptions of unused keyslot are fixable. This
+command will only change the LUKS header, not any key-slot data. You may
+enforce LUKS version by adding --type option.
+
+It also repairs (upgrades) LUKS2 reencryption metadata by adding
+a metadata digest that protects it against malicious changes.
+
+If LUKS2 reencryption was interrupted in the middle of writing
+reencryption segment the repair command can be used to perform
+reencryption recovery so that reencryption can continue later.
+
+*WARNING:* Always create a binary backup of the original header before
+calling this command.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-resize.8.adoc

@@ -0,0 +1,42 @@
+= cryptsetup-resize(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_RESIZE:
+
+== Name
+
+cryptsetup-resize - resize an active mapping
+
+== SYNOPSIS
+
+*cryptsetup _resize_ [<options>] <name>*
+
+== DESCRIPTION
+
+Resizes an active mapping <name>.
+
+If --size (in 512-bytes sectors) or --device-size are not specified, the
+size is computed from the underlying device. For LUKS it is the size of
+the underlying device without the area reserved for LUKS header (see
+data payload offset in *luksDump* command). For plain crypt device, the
+whole device size is used.
+
+Note that this does not change the raw device geometry, it just changes
+how many sectors of the raw device are represented in the mapped device.
+
+If cryptsetup detected volume key for active device loaded in kernel
+keyring service, resize action would first try to retrieve the key using
+a token. Only if it failed, it'd ask for a passphrase to unlock a
+keyslot (LUKS) or to derive a volume key again (plain mode). The kernel
+keyring is used by default for LUKS2 devices.
+
+With LUKS2 device additional *<options>* can be [--token-id,
+--token-only, --token-type, --key-slot, --key-file, --keyfile-size,
+--keyfile-offset, --timeout, --disable-external-tokens, --disable-locks,
+--disable-keyring].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-ssh.8

@@ -1,84 +0,0 @@
-.TH CRYPTSETUP-SSH "8" "June 2021" "cryptsetup-ssh" "Maintenance Commands"
-.SH NAME
-cryptsetup-ssh \- manage LUKS2 SSH token
-.SH SYNOPSIS
-.B cryptsetup-ssh
-\fI\,<options> <action> <action args>\/\fR
-.SH DESCRIPTION
-Experimental cryptsetup plugin for unlocking LUKS2 devices with token connected
-to an SSH server.
-
-This plugin currently allows only adding a token to an existing key slot, see \fBcryptsetup(8)\fP
-for instruction on how to remove, import or export the token.
-
-.SS Add operation
-.PP
-\fIadd\fR <options> <device>
-.IP
-Adds the SSH token to \fB<device>\fR.
-
-Specified SSH server must contain a key file on the specified path with a
-passphrase for an existing key slot on the device.
-Provided credentials will be used by cryptsetup to get the password when
-opening the device using the token.
-
-\-\-ssh\-server, \-\-ssh\-user, \-\-ssh\-keypath and -\-ssh\-path
-are required for this operation.
-
-.TP
-\fB\-\-key\-slot\fR=\fI\,NUM\/\fR
-Keyslot to assign the token to. If not specified, the token will be assigned to the first key slot
-matching provided passphrase.
-.TP
-\fB\-\-ssh\-keypath\fR=\fI\,STRING\/\fR
-Path to the SSH key for connecting to the remote server.
-.TP
-\fB\-\-ssh\-path\fR=\fI\,STRING\/\fR
-Path to the key file on the remote server.
-.TP
-\fB\-\-ssh\-server\fR=\fI\,STRING\/\fR
-IP address/URL of the remote server for this token.
-.TP
-\fB\-\-ssh\-user\fR=\fI\,STRING\/\fR
-Username used for the remote server.
-.IP
-
-.SH OPTIONS
-.TP
-\fB\-\-debug\fR
-Show debug messages
-.TP
-\fB\-\-debug\-json\fR
-Show debug messages including JSON metadata
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Shows more detailed error messages
-.TP
-\-?, \fB\-\-help\fR
-Show help
-.TP
-\fB\-V\fR, \fB\-\-version\fR
-Print program version
-.PP
-
-.SH NOTES
-The information provided when adding the token (SSH server address, user and paths) will be stored in the LUKS2 header in plaintext.
-
-.SH REPORTING BUGS
-Report bugs, including ones in the documentation, on
-the cryptsetup mailing list at <cryptsetup@lists.linux.dev>
-or in the 'Issues' section on LUKS website.
-Please attach the output of the failed command with the
-\-\-debug option added.
-
-.SH COPYRIGHT
-Copyright \(co 2016-2022 Red Hat, Inc.
-.br
-Copyright \(co 2016-2022 Milan Broz
-.br
-Copyright \(co 2021-2022 Vojtech Trefny
-
-This is free software; see the source for copying conditions.  There is NO
-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-.SH SEE ALSO
-The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR

man/cryptsetup-ssh.8.adoc

@@ -0,0 +1,80 @@
+= cryptsetup-ssh(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup-ssh {release-version}
+:man-linkstyle: pass:[blue R < >]
+
+== NAME
+
+cryptsetup-ssh - manage LUKS2 SSH token
+
+== SYNOPSIS
+
+*cryptsetup-ssh <action> [<options>] <action args>*
+
+== DESCRIPTION
+
+Experimental cryptsetup plugin for unlocking LUKS2 devices with token
+connected to an SSH server.
+
+This plugin currently allows only adding a token to an existing key
+slot. See *cryptsetup(8)* for instructions on how to remove, import or
+export the token.
+
+=== Add operation
+
+*add <options> <device>*
+
+Adds the SSH token to *<device>*.
+
+The specified SSH server must contain a key file on the specified path with
+a passphrase for an existing key slot on the device. Provided
+credentials will be used by cryptsetup to get the password when opening
+the device using the token.
+
+Options --ssh-server, --ssh-user, --ssh-keypath and --ssh-path are
+required for this operation.
+
+== OPTIONS
+
+**--key-slot**=_NUM_::
+Keyslot to assign the token to. If not specified, the token will be
+assigned to the first key slot matching provided passphrase.
+
+**--ssh-keypath**=_STRING_::
+Path to the SSH key for connecting to the remote server.
+
+**--ssh-path**=_STRING_::
+Path to the key file on the remote server.
+
+**--ssh-server**=_STRING_::
+IP address/URL of the remote server for this token.
+
+**--ssh-user**=_STRING_::
+Username used for the remote server.
+
+*--debug*::
+Show debug messages
+
+*--debug-json*::
+Show debug messages including JSON metadata
+
+*--verbose, -v*::
+Shows more detailed error messages
+
+*--help, -?*::
+Show help
+
+*--version, -V*::
+Print program version
+
+== NOTES
+
+The information provided when adding the token (SSH server address, user
+and paths) will be stored in the LUKS2 header in plaintext.
+
+== AUTHORS
+
+The cryptsetup-ssh tool is written by Vojtech Trefny.
+
+include::man/common_footer.adoc[]

man/cryptsetup-status.8.adoc

@@ -0,0 +1,22 @@
+= cryptsetup-status(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_STATUS:
+
+== Name
+
+cryptsetup-status - report the status for a mapping
+
+== SYNOPSIS
+
+*cryptsetup _status_ [<options>] <name>*
+
+== DESCRIPTION
+
+Reports the status for the mapping <name>.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-tcryptDump.8.adoc

@@ -0,0 +1,35 @@
+= cryptsetup-tcryptDump(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_TCRYPTDUMP:
+
+== Name
+
+cryptsetup-tcryptDump - dump the header information of a TCRYPT (TrueCrypt or VeraCrypt compatible) device
+
+== SYNOPSIS
+
+*cryptsetup _tcryptDump_ [<options>] <device>*
+
+== DESCRIPTION
+
+Dump the header information of a TCRYPT (TrueCrypt or VeraCrypt compatible) device.
+
+If the --dump-volume-key option is used, the TCRYPT device volume key is
+dumped instead of TCRYPT header info. Beware that the volume key (or
+concatenated volume keys if cipher chain is used) can be used to decrypt
+the data stored in the TCRYPT container without a passphrase. This means
+that if the volume key is compromised, the whole device has to be erased
+to prevent further access. Use this option carefully.
+
+*<options>* can be [--dump-volume-key, --key-file, --tcrypt-hidden,
+--tcrypt-system, --tcrypt-backup, --cipher, --hash].
+
+The keyfile parameter allows a combination of file content with the
+passphrase and can be repeated.
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup-token.8.adoc

@@ -0,0 +1,52 @@
+= cryptsetup-token(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+:COMMON_OPTIONS:
+:ACTION_TOKEN:
+
+== Name
+
+cryptsetup-token - manage LUKS2 tokens
+
+== SYNOPSIS
+
+*cryptsetup _token_ <add|remove|import|export> [<options>] <device>*
+
+== DESCRIPTION
+
+Action _add_ creates a new keyring token to enable auto-activation of the
+device. For the auto-activation, the passphrase must be stored in
+keyring with the specified description. Usually, the passphrase should
+be stored in _user_ or _user-session_ keyring. The _token_ command is
+supported only for LUKS2.
+
+For adding new keyring token, option --key-description is mandatory.
+Also, new token is assigned to key slot specified with --key-slot option
+or to all active key slots in the case --key-slot option is omitted.
+
+To remove existing token, specify the token ID which should be removed
+with --token-id option.
+
+*WARNING:* The action _token remove_ removes any token type, not just
+_keyring_ type from token slot specified by --token-id option.
+
+Action _import_ can store arbitrary valid token json in LUKS2 header. It
+may be passed via standard input or via file passed in --json-file
+option. If you specify --key-slot then successfully imported token is
+also assigned to the key slot.
+
+Action _export_ writes requested token JSON to a file passed with
+--json-file or to standard output.
+
+If --token-id is used with action _add_ or action _import_ and a token
+with that ID already exists, option --token-replace can be used to
+replace the existing token.
+
+*<options>* can be [--header, --token-id, --key-slot, --key-description,
+--disable-external-tokens, --disable-locks, --disable-keyring,
+--json-file, --token-replace].
+
+include::man/common_options.adoc[]
+include::man/common_footer.adoc[]

man/cryptsetup.8.adoc

@@ -0,0 +1,685 @@
+= cryptsetup(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: cryptsetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+
+== Name
+
+cryptsetup - manage plain dm-crypt, LUKS, and other encrypted volumes
+
+== SYNOPSIS
+
+*cryptsetup <action> [<options>] <action args>*
+
+== DESCRIPTION
+
+cryptsetup is used to conveniently setup dm-crypt managed device-mapper
+mappings. These include plain dm-crypt volumes and LUKS volumes. The
+difference is that LUKS uses a metadata header and can hence offer more
+features than plain dm-crypt. On the other hand, the header is visible
+and vulnerable to damage.
+
+In addition, cryptsetup provides limited support for the use of loop-AES
+volumes, TrueCrypt, VeraCrypt, and BitLocker compatible volumes.
+
+For more information about specific cryptsetup action see
+*cryptsetup-<action>*(8), where *<action>* is the name of the
+cryptsetup action.
+
+== BASIC ACTIONS
+
+The following are valid actions for all supported device types.
+
+=== OPEN
+*open <device> <name> --type <device_type>*
+
+Opens (creates a mapping with) <name> backed by device <device>. +
+See *cryptsetup-open*(8).
+
+=== CLOSE
+*close <name>*
+
+Removes the existing mapping <name> and wipes the key from kernel memory. +
+See *cryptsetup-close*(8).
+
+=== STATUS
+*status <name>*
+
+Reports the status for the mapping <name>. +
+See *cryptsetup-status*(8).
+
+=== RESIZE
+*resize <name>*
+
+Resizes an active mapping <name>. +
+See *cryptsetup-resize*(8).
+
+=== REFRESH
+*refresh <name>*
+
+Refreshes parameters of active mapping <name>. +
+See *cryptsetup-refresh*(8).
+
+=== REENCRYPT
+*reencrypt <device> or --active-name <name> [<new_name>]*
+
+Run LUKS device reencryption. +
+See *cryptsetup-reencrypt*(8).
+
+== PLAIN MODE
+
+Plain dm-crypt encrypts the device sector-by-sector with a single,
+non-salted hash of the passphrase. No checks are performed, no metadata
+is used. There is no formatting operation. When the raw device is mapped
+(opened), the usual device operations can be used on the mapped device,
+including filesystem creation. Mapped devices usually reside in
+/dev/mapper/<name>.
+
+The following are valid plain device type actions:
+
+=== OPEN
+*open --type plain <device> <name>* +
+create <name> <device> (*OBSOLETE syntax*)
+
+Opens (creates a mapping with) <name> backed by device <device>. +
+See *cryptsetup-open*(8).
+
+== LUKS EXTENSION
+
+LUKS, the Linux Unified Key Setup, is a standard for disk encryption. It
+adds a standardized header at the start of the device, a key-slot area
+directly behind the header and the bulk data area behind that. The whole
+set is called a 'LUKS container'. The device that a LUKS container
+resides on is called a 'LUKS device'. For most purposes, both terms can
+be used interchangeably. But note that when the LUKS header is at a
+nonzero offset in a device, then the device is not a LUKS device
+anymore, but has a LUKS container stored in it at an offset.
+
+LUKS can manage multiple passphrases that can be individually revoked or
+changed and that can be securely scrubbed from persistent media due to
+the use of anti-forensic stripes. Passphrases are protected against
+brute-force and dictionary attacks by Password-Based Key Derivation
+Function (PBKDF).
+
+LUKS2 is a new version of header format that allows additional
+extensions like different PBKDF algorithm or authenticated encryption.
+You can format device with LUKS2 header if you specify *--type luks2* in
+*luksFormat* command. For activation, the format is already recognized
+automatically.
+
+Each passphrase, also called a *key* in this document, is associated
+with one of 8 key-slots. Key operations that do not specify a slot
+affect the first slot that matches the supplied passphrase or the first
+empty slot if a new passphrase is added.
+
+The *<device>* parameter can also be specified by a LUKS UUID in the
+format UUID=<uuid>. Translation to real device name uses symlinks in
+/dev/disk/by-uuid directory.
+
+To specify a detached header, the *--header* parameter can be used in
+all LUKS commands and always takes precedence over the positional
+*<device>* parameter.
+
+The following are valid LUKS actions:
+
+=== FORMAT
+*luksFormat <device> [<key file>]*
+
+Initializes a LUKS partition and sets the initial passphrase (for key-slot 0). +
+See *cryptsetup-luksFormat*(8).
+
+=== OPEN
+*open --type luks <device> <name>* +
+luksOpen <device> <name> (*old syntax*)
+
+Opens the LUKS device <device> and sets up a mapping <name> after
+successful verification of the supplied passphrase. +
+See *cryptsetup-open*(8).
+
+=== SUSPEND
+*luksSuspend <name>*
+
+Suspends an active device (all IO operations will block and accesses to
+the device will wait indefinitely) and wipes the encryption key from
+kernel memory. +
+See *cryptsetup-luksSuspend*(8).
+
+=== RESUME
+*luksResume <name>*
+
+Resumes a suspended device and reinstates the encryption key. +
+See *cryptsetup-luksResume*(8).
+
+=== ADD KEY
+*luksAddKey <device> [<key file with new key>]*
+
+Adds a new passphrase using an existing passphrase. +
+See *cryptsetup-luksAddKey*(8).
+
+=== REMOVE KEY
+*luksRemoveKey <device> [<key file with passphrase to be removed>]*
+
+Removes the supplied passphrase from the LUKS device. +
+See *cryptsetup-luksRemoveKey*(8).
+
+=== CHANGE KEY
+*luksChangeKey <device> [<new key file>]*
+
+Changes an existing passphrase. +
+See *cryptsetup-luksChangeKey*(8).
+
+=== CONVERT KEY
+*luksConvertKey <device>*
+
+Converts an existing LUKS2 keyslot to new PBKDF parameters. +
+See *cryptsetup-luksConvertKey*(8).
+
+=== KILL SLOT
+*luksKillSlot <device> <key slot number>*
+
+Wipe the key-slot number <key slot> from the LUKS device. +
+See *cryptsetup-luksKillSlot*(8).
+
+=== ERASE
+*erase <device>* +
+luksErase <device> (*old syntax*)
+
+Erase all keyslots and make the LUKS container permanently inaccessible. +
+See *cryptsetup-erase*(8).
+
+=== UUID
+*luksUUID <device>*
+
+Print or set the UUID of a LUKS device. +
+See *cryptsetup-luksUUID*(8).
+
+=== IS LUKS
+*isLuks <device>*
+
+Returns true, if <device> is a LUKS device, false otherwise. +
+See *cryptsetup-isLuks*(8).
+
+=== DUMP
+*luksDump <device>*
+
+Dump the header information of a LUKS device. +
+See *cryptsetup-luksDump*(8).
+
+=== HEADER BACKUP
+*luksHeaderBackup <device> --header-backup-file <file>*
+
+Stores a binary backup of the LUKS header and keyslot area. +
+See *cryptsetup-luksHeaderBackup*(8).
+
+=== HEADER RESTORE
+*luksHeaderRestore <device> --header-backup-file <file>*
+
+Restores a binary backup of the LUKS header and keyslot area from the
+specified file. +
+See *cryptsetup-luksHeaderRestore*(8).
+
+=== TOKEN
+*token <add|remove|import|export> <device>*
+
+Manipulate token objects used for obtaining passphrases. +
+See *cryptsetup-token*(8).
+
+=== CONVERT
+*convert <device> --type <format>*
+
+Converts the device between LUKS1 and LUKS2 format (if possible). +
+See *cryptsetup-convert*(8).
+
+=== CONFIG
+*config <device>*
+
+Set permanent configuration options (store to LUKS header). +
+See *cryptsetup-config*(8).
+
+== loop-AES EXTENSION
+
+cryptsetup supports mapping loop-AES encrypted partition using a
+compatibility mode.
+
+=== OPEN
+*open --type loopaes <device> <name> --key-file <keyfile>* +
+loopaesOpen <device> <name> --key-file <keyfile> (*old syntax*)
+
+Opens the loop-AES <device> and sets up a mapping <name>. +
+See *cryptsetup-open*(8).
+
+See also section 7 of the FAQ and http://loop-aes.sourceforge.net[loop-AES]
+for more information regarding loop-AES.
+
+== TCRYPT (TrueCrypt and VeraCrypt compatible) EXTENSION
+
+cryptsetup supports mapping of TrueCrypt, tcplay or VeraCrypt encrypted
+partition using a native Linux kernel API. Header formatting and TCRYPT
+header change is not supported, cryptsetup never changes TCRYPT header
+on-device.
+
+TCRYPT extension requires kernel userspace crypto API to be available
+(introduced in Linux kernel 2.6.38). If you are configuring kernel
+yourself, enable "User-space interface for symmetric key cipher
+algorithms" in "Cryptographic API" section
+(CRYPTO_USER_API_SKCIPHER .config option).
+
+Because TCRYPT header is encrypted, you have to always provide valid
+passphrase and keyfiles.
+
+Cryptsetup should recognize all header variants, except legacy cipher
+chains using LRW encryption mode with 64 bits encryption block (namely
+Blowfish in LRW mode is not recognized, this is limitation of kernel
+crypto API).
+
+VeraCrypt is extension of TrueCrypt header with increased iteration
+count so unlocking can take quite a lot of time.
+
+To open a VeraCrypt device with a custom Personal Iteration Multiplier
+(PIM) value, use either the *--veracrypt-pim=<PIM>* option to directly
+specify the PIM on the command- line or use *--veracrypt-query-pim* to
+be prompted for the PIM.
+
+The PIM value affects the number of iterations applied during key
+derivation. Please refer to
+https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html[PIM]
+for more detailed information.
+
+If you need to disable VeraCrypt device support, use
+*--disable-veracrypt* option.
+
+*NOTE:* Activation with *tcryptOpen* is supported only for cipher chains
+using LRW or XTS encryption modes.
+
+The *tcryptDump* command should work for all recognized TCRYPT devices
+and doesn't require superuser privilege.
+
+To map system device (device with boot loader where the whole encrypted
+system resides) use *--tcrypt-system* option. You can use partition
+device as the parameter (parameter must be real partition device, not an
+image in a file), then only this partition is mapped.
+
+If you have the whole TCRYPT device as a file image and you want to map
+multiple partition encrypted with system encryption, please create
+loopback mapping with partitions first (*losetup -P*, see *losetup(8)*
+man page for more info), and use loop partition as the device parameter.
+
+If you use the whole base device as a parameter, one device for the
+whole system encryption is mapped. This mode is available only for
+backward compatibility with older cryptsetup versions which mapped
+TCRYPT system encryption using the whole device.
+
+To use hidden header (and map hidden device, if available), use
+*--tcrypt-hidden* option.
+
+To explicitly use backup (secondary) header, use *--tcrypt-backup*
+option.
+
+*NOTE:* There is no protection for a hidden volume if the outer volume
+is mounted. The reason is that if there were any protection, it would
+require some metadata describing what to protect in the outer volume and
+the hidden volume would become detectable.
+
+=== OPEN
+*open --type tcrypt <device> <name>* +
+tcryptOpen_ <device> <name> (*old syntax*)
+
+Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a mapping
+<name>. +
+See *cryptsetup-open*(8).
+
+=== DUMP
+*tcryptDump <device>*
+
+Dump the header information of a TCRYPT device. +
+See *cryptsetup-tcryptDump*(8).
+
+See also https://en.wikipedia.org/wiki/TrueCrypt[*TrueCrypt*] and
+https://en.wikipedia.org/wiki/VeraCrypt[*VeraCrypt*] pages for more information.
+
+Please note that cryptsetup does not use TrueCrypt or VeraCrypt code, please
+report all problems related to this compatibility extension to the cryptsetup
+project.
+
+== BITLK (Windows BitLocker compatible) EXTENSION
+
+cryptsetup supports mapping of BitLocker and BitLocker to Go encrypted
+partition using a native Linux kernel API. Header formatting and BITLK
+header changes are not supported, cryptsetup never changes BITLK header
+on-device.
+
+BITLK extension requires kernel userspace crypto API to be available
+(for details see TCRYPT section).
+
+Cryptsetup should recognize all BITLK header variants, except legacy
+header used in Windows Vista systems and partially decrypted BitLocker
+devices. Activation of legacy devices encrypted in CBC mode requires at
+least Linux kernel version 5.3 and for devices using Elephant diffuser
+kernel 5.6.
+
+The *bitlkDump* command should work for all recognized BITLK devices and
+doesn't require superuser privilege.
+
+For unlocking with the *open* a password or a recovery passphrase or a
+startup key must be provided.
+
+Additionally unlocking using volume key is supported. You must provide
+BitLocker Full Volume Encryption Key (FVEK) using the --volume-key-file
+option. The key must be decrypted and without the header (only
+128/256/512 bits of key data depending on used cipher and mode).
+
+Other unlocking methods (TPM, SmartCard) are not supported.
+
+=== OPEN
+*open --type bitlk <device> <name>* +
+bitlkOpen <device> <name> (*old syntax*)
+
+Opens the BITLK (a BitLocker-compatible) <device> and sets up a mapping
+<name>. +
+See *cryptsetup-open*(8).
+
+=== DUMP
+*bitlkDump <device>*
+
+Dump the header information of a BITLK device. +
+See *cryptsetup-bitlkDump*(8).
+
+Please note that cryptsetup does not use any Windows BitLocker code,
+please report all problems related to this compatibility extension to
+the cryptsetup project.
+
+== MISCELLANEOUS ACTIONS
+
+=== REPAIR
+*repair <device>*
+
+Tries to repair the device metadata if possible. Currently supported
+only for LUKS device type. +
+See *cryptsetup-repair*(8).
+
+=== BENCHMARK
+*benchmark <options>*
+
+Benchmarks ciphers and KDF (key derivation function). +
+See *cryptsetup-benchmark*(8).
+
+== PLAIN DM-CRYPT OR LUKS?
+
+Unless you understand the cryptographic background well, use LUKS. With
+plain dm-crypt there are a number of possible user errors that massively
+decrease security. While LUKS cannot fix them all, it can lessen the
+impact for many of them.
+
+== WARNINGS
+
+A lot of good information on the risks of using encrypted storage, on
+handling problems and on security aspects can be found in the
+Cryptsetup FAQ. Read it. Nonetheless, some risks deserve to be
+mentioned here.
+
+*Backup:* Storage media die. Encryption has no influence on that. Backup
+is mandatory for encrypted data as well, if the data has any worth. See
+the Cryptsetup FAQ for advice on how to do a backup of an encrypted
+volume.
+
+*Character encoding:* If you enter a passphrase with special symbols,
+the passphrase can change depending on character encoding. Keyboard
+settings can also change, which can make blind input hard or impossible.
+For example, switching from some ASCII 8-bit variant to UTF-8 can lead
+to a different binary encoding and hence different passphrase seen by
+cryptsetup, even if what you see on the terminal is exactly the same. It
+is therefore highly recommended to select passphrase characters only
+from 7-bit ASCII, as the encoding for 7-bit ASCII stays the same for all
+ASCII variants and UTF-8.
+
+*LUKS header:* If the header of a LUKS volume gets damaged, all data is
+permanently lost unless you have a header-backup. If a key-slot is
+damaged, it can only be restored from a header-backup or if another
+active key-slot with known passphrase is undamaged. Damaging the LUKS
+header is something people manage to do with surprising frequency. This
+risk is the result of a trade-off between security and safety, as LUKS
+is designed for fast and secure wiping by just overwriting header and
+key-slot area.
+
+*Previously used partitions:* If a partition was previously used, it is
+a very good idea to wipe filesystem signatures, data, etc. before
+creating a LUKS or plain dm-crypt container on it. For a quick removal
+of filesystem signatures, use *wipefs*(8). Take care though that this may
+not remove everything. In particular, MD RAID signatures at the end of a
+device may survive. It also does not remove data. For a full wipe,
+overwrite the whole partition before container creation. If you do not
+know how to do that, the cryptsetup FAQ describes several options.
+
+== EXAMPLES
+
+Example 1: Create LUKS 2 container on block device /dev/sdX.::
+  sudo cryptsetup --type luks2 luksFormat /dev/sdX
+Example 2: Add an additional passphrase to key slot 5.::
+  sudo cryptsetup luksAddKey --key-slot 5 /dev/sdX
+Example 3: Create LUKS header backup and save it to file.::
+  sudo cryptsetup luksHeaderBackup /dev/sdX --header-backup-file
+  /var/tmp/NameOfBackupFile
+Example 4: Open LUKS container on /dev/sdX and map it to sdX_crypt.::
+  sudo cryptsetup open /dev/sdX sdX_crypt
+*WARNING: The command in example 5 will erase all key slots.*::
+  Your cannot use your LUKS container afterward anymore unless you have
+  a backup to restore.
+Example 5: Erase all key slots on /dev/sdX.::
+  sudo cryptsetup erase /dev/sdX
+Example 6: Restore LUKS header from backup file.::
+  sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file
+  /var/tmp/NameOfBackupFile
+
+== RETURN CODES
+
+Cryptsetup returns *0* on success and a non-zero value on error.
+
+Error codes are: *1* wrong parameters, *2* no permission (bad passphrase),
+*3* out of memory, *4* wrong device specified, *5* device already exists
+or device is busy.
+
+== NOTES
+
+=== Passphrase processing for PLAIN mode
+
+Note that no iterated hashing or salting is done in plain mode. If
+hashing is done, it is a single direct hash. This means that low-entropy
+passphrases are easy to attack in plain mode.
+
+*From a terminal*: The passphrase is read until the first newline, i.e.
+'\n'. The input without the newline character is processed with the
+default hash or the hash specified with --hash. The hash result will be
+truncated to the key size of the used cipher, or the size specified with
+-s.
+
+*From stdin*: Reading will continue until a newline (or until the
+maximum input size is reached), with the trailing newline stripped. The
+maximum input size is defined by the same compiled-in default as for the
+maximum key file size and can be overwritten using --keyfile-size
+option.
+
+The data read will be hashed with the default hash or the hash specified
+with --hash. The hash result will be truncated to the key size of the
+used cipher, or the size specified with -s.
+
+Note that if --key-file=- is used for reading the key from stdin,
+trailing newlines are not stripped from the input.
+
+If "plain" is used as argument to --hash, the input data will not be
+hashed. Instead, it will be zero padded (if shorter than the key size)
+or truncated (if longer than the key size) and used directly as the
+binary key. This is useful for directly specifying a binary key. No
+warning will be given if the amount of data read from stdin is less than
+the key size.
+
+*From a key file*: It will be truncated to the key size of the used
+cipher or the size given by -s and directly used as a binary key.
+
+*WARNING*: The --hash argument is being ignored. The --hash option is
+usable only for stdin input in plain mode.
+
+If the key file is shorter than the key, cryptsetup will quit with an
+error. The maximum input size is defined by the same compiled-in default
+as for the maximum key file size and can be overwritten using
+--keyfile-size option.
+
+=== Passphrase processing for LUKS
+
+LUKS uses PBKDF to protect against dictionary attacks and to give some
+protection to low-entropy passphrases (see cryptsetup FAQ).
+
+*From a terminal*: The passphrase is read until the first newline and
+then processed by PBKDF2 without the newline character.
+
+*From stdin*: LUKS will read passphrases from stdin up to the first
+newline character or the compiled-in maximum key file length. If
+--keyfile-size is given, it is ignored.
+
+*From key file*: The complete keyfile is read up to the compiled-in
+maximum size. Newline characters do not terminate the input. The
+--keyfile-size option can be used to limit what is read.
+
+*Passphrase processing*: Whenever a passphrase is added to a LUKS header
+(luksAddKey, luksFormat), the user may specify how much the time the
+passphrase processing should consume. The time is used to determine the
+iteration count for PBKDF2 and higher times will offer better protection
+for low-entropy passphrases, but open will take longer to complete. For
+passphrases that have entropy higher than the used key length, higher
+iteration times will not increase security.
+
+The default setting of one or two seconds is sufficient for most
+practical cases. The only exception is a low-entropy passphrase used on
+a device with a slow CPU, as this will result in a low iteration count.
+On a slow device, it may be advisable to increase the iteration time
+using the --iter-time option in order to obtain a higher iteration
+count. This does slow down all later luksOpen operations accordingly.
+
+=== Incoherent behavior for invalid passphrases/keys
+
+LUKS checks for a valid passphrase when an encrypted partition is
+unlocked. The behavior of plain dm-crypt is different. It will always
+decrypt with the passphrase given. If the given passphrase is wrong, the
+device mapped by plain dm-crypt will essentially still contain encrypted
+data and will be unreadable.
+
+=== Supported ciphers, modes, hashes and key sizes
+
+The available combinations of ciphers, modes, hashes and key sizes
+depend on kernel support. See /proc/crypto for a list of available
+options. You might need to load additional kernel crypto modules in
+order to get more options.
+
+For the --hash option, if the crypto backend is libgcrypt, then all
+algorithms supported by the gcrypt library are available. For other
+crypto backends, some algorithms may be missing.
+
+=== Notes on passphrases
+
+Mathematics can't be bribed. Make sure you keep your passphrases safe.
+There are a few nice tricks for constructing a fallback, when suddenly
+out of the blue, your brain refuses to cooperate. These fallbacks need
+LUKS, as it's only possible with LUKS to have multiple passphrases.
+Still, if your attacker model does not prevent it, storing your
+passphrase in a sealed envelope somewhere may be a good idea as well.
+
+=== Notes on Random Number Generators
+
+Random Number Generators (RNG) used in cryptsetup are always the kernel
+RNGs without any modifications or additions to data stream produced.
+
+There are two types of randomness cryptsetup/LUKS needs. One type (which
+always uses /dev/urandom) is used for salts, the AF splitter and for
+wiping deleted keyslots.
+
+The second type is used for the volume key. You can switch between using
+/dev/random and /dev/urandom here, see *--use-random* and
+*--use-urandom* options. Using /dev/random on a system without enough
+entropy sources can cause *luksFormat* to block until the requested
+amount of random data is gathered. In a low-entropy situation (embedded
+system), this can take a very long time and potentially forever. At the
+same time, using /dev/urandom in a low-entropy situation will produce
+low-quality keys. This is a serious problem, but solving it is out of
+scope for a mere man-page. See *urandom(4)* for more information.
+
+=== Authenticated disk encryption (EXPERIMENTAL)
+
+Since Linux kernel version 4.12 dm-crypt supports authenticated disk
+encryption.
+
+Normal disk encryption modes are length-preserving (plaintext sector is
+of the same size as a ciphertext sector) and can provide only
+confidentiality protection, but not cryptographically sound data
+integrity protection.
+
+Authenticated modes require additional space per-sector for
+authentication tag and use Authenticated Encryption with Additional Data
+(AEAD) algorithms.
+
+If you configure LUKS2 device with data integrity protection, there will
+be an underlying dm-integrity device, which provides additional
+per-sector metadata space and also provide data journal protection to
+ensure atomicity of data and metadata update. Because there must be
+additional space for metadata and journal, the available space for the
+device will be smaller than for length-preserving modes.
+
+The dm-crypt device then resides on top of such a dm-integrity device.
+All activation and deactivation of this device stack is performed by
+cryptsetup, there is no difference in using *luksOpen* for integrity
+protected devices. If you want to format LUKS2 device with data
+integrity protection, use *--integrity* option.
+
+Since dm-integrity doesn't support discards (TRIM), dm-crypt device on
+top of it inherits this, so integrity protection mode doesn't support
+discards either.
+
+Some integrity modes requires two independent keys (key for encryption
+and for authentication). Both these keys are stored in one LUKS keyslot.
+
+*WARNING:* 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. 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.
+
+=== Notes on loopback device use
+
+Cryptsetup is usually used directly on a block device (disk partition or
+LVM volume). However, if the device argument is a file, cryptsetup tries
+to allocate a loopback device and map it into this file. This mode
+requires Linux kernel 2.6.25 or more recent which supports the loop
+autoclear flag (loop device is cleared on the last close automatically).
+Of course, you can always map a file to a loop-device manually. See the
+cryptsetup FAQ for an example.
+
+When device mapping is active, you can see the loop backing file in the
+status command output. Also see losetup(8).
+
+=== LUKS2 header locking
+
+The LUKS2 on-disk metadata is updated in several steps and to achieve
+proper atomic update, there is a locking mechanism. For an image in
+file, code uses *flock(2)* system call. For a block device, lock is
+performed over a special file stored in a locking directory (by default
+*/run/cryptsetup*). The locking directory should be created with the
+proper security context by the distribution during the boot-up phase.
+Only LUKS2 uses locks, other formats do not use this mechanism.
+
+=== LUKS on-disk format specification
+
+For LUKS on-disk metadata specification see
+https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification[*LUKS1*] and
+https://gitlab.com/cryptsetup/LUKS2-docs[*LUKS2*].
+
+== AUTHORS
+
+Cryptsetup is originally written by mailto:jana@saout.de[Jana Saout]. +
+The LUKS extensions and original man page were written by
+mailto:clemens@endorphin.org[Clemens Fruhwirth]. +
+Man page extensions by mailto:gmazyland@gmail.com[Milan Broz]. +
+Man page rewrite and extension by mailto:arno@wagner.name[Arno Wagner].
+
+include::man/common_footer.adoc[]

man/integritysetup.8

@@ -1,309 +0,0 @@
-.TH INTEGRITYSETUP "8" "January 2021" "integritysetup" "Maintenance Commands"
-.SH NAME
-integritysetup - manage dm-integrity (block level integrity) volumes
-.SH SYNOPSIS
-.B integritysetup <options> <action> <action args>
-.SH DESCRIPTION
-.PP
-Integritysetup is used to configure dm-integrity managed device-mapper mappings.
-
-Device-mapper integrity target provides read-write transparent integrity
-checking of block devices. The dm-integrity target emulates additional data
-integrity field per-sector. You can use this additional field directly
-with integritysetup utility, or indirectly (for authenticated encryption)
-through cryptsetup.
-
-Integritysetup supports these operations:
-.PP
-\fIformat\fR <device>
-.IP
-Formats <device> (calculates space and dm-integrity superblock and wipes the device).
-
-\fB<options>\fR can be [\-\-data\-device, \-\-batch\-mode, \-\-no\-wipe, \-\-journal\-size,
-\-\-interleave\-sectors, \-\-tag\-size, \-\-integrity, \-\-integrity\-key\-size,
-\-\-integrity\-key\-file, \-\-sector\-size, \-\-progress\-frequency, \-\-progress\-json]
-
-.PP
-\fIopen\fR <device> <name>
-.br
-\fIcreate\fR <name> <device> (\fBOBSOLETE syntax\fR)
-.IP
-Open a mapping with <name> backed by device <device>.
-
-\fB<options>\fR can be [\-\-data\-device, \-\-batch\-mode, \-\-journal\-watermark,
-\-\-journal\-commit\-time, \-\-buffer\-sectors, \-\-integrity, \-\-integrity\-key\-size,
-\-\-integrity\-key\-file, \-\-integrity\-no\-journal, \-\-integrity\-recalculate,
-\-\-integrity\-recalculate-reset,\-\-integrity\-recovery\-mode, \-\-allow\-discards]
-
-.PP
-\fIclose\fR <name>
-.IP
-Removes existing mapping <name>.
-
-For backward compatibility, there is \fBremove\fR command alias
-for the \fBclose\fR command.
-
-\fB<options>\fR can be [\-\-deferred] or [\-\-cancel\-deferred]
-
-.PP
-\fIstatus\fR <name>
-.IP
-Reports status for the active integrity mapping <name>.
-.PP
-\fIdump\fR <device>
-.IP
-Reports parameters from on-disk stored superblock.
-
-.PP
-\fIresize\fR <name>
-.IP
-Resizes an active mapping <name>.
-
-If \-\-size (in 512-bytes sectors) or \-\-device\-size are not specified,
-the size is computed from the underlying device. After resize, the
-\fBrecalculating\fR flag is set. If \-\-wipe flag is set and the size of the
-device is increased, the newly added section will be wiped.
-
-Increasing the size of integrity volumes is available since the Linux kernel
-version 5.7, shrinking should work on older kernels too.
-
-\fB<options>\fR can be [\-\-size, \-\-device\-size, \-\-wipe]
-
-.SH OPTIONS
-.TP
-.B "\-\-verbose, \-v"
-Print more information on command execution.
-.TP
-.B "\-\-debug"
-Run in debug mode with full diagnostic logs. Debug output
-lines are always prefixed by '#'.
-.TP
-.B "\-\-version"
-Show the program version.
-.TP
-.B "\-\-batch\-mode"
-Do not ask for confirmation.
-.TP
-.B "\-\-progress-frequency <seconds>"
-Print separate line every <seconds> with wipe progress.
-.TP
-.B "\-\-progress-json"
-Prints wipe progress data in json format suitable mostly for machine processing.
-It prints separate line every half second (or based on \fI\-\-progress\-frequency\fR value).
-The json output looks as follows during wipe progress (except it's compact single line):
-.EX
-{
-  "device":"/dev/sda"       // backing device or file
-  "device_bytes":"8192",    // bytes wiped so far
-  "device_size":"44040192", // total bytes to wipe
-  "speed":"126877696",      // calculated speed in bytes per second (based on progress so far)
-  "eta_ms":"2520012"        // estimated time to finish wipe in milliseconds
-  "time_ms":"5561235"       // total time spent wiping device in milliseconds
-}
-.EE
-
-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.
-.TP
-.B "\-\-no\-wipe"
-Do not wipe the device after format. A device that is not initially wiped will contain invalid checksums.
-.TP
-.B "\-\-wipe"
-Wipe the newly allocated area after resize to bigger size. If this flag is not set, checksums will be calculated for the data previously stored in the newly allocated area.
-.TP
-.B "\-\-journal\-size, \-j BYTES"
-Size of the journal.
-.TP
-.B "\-\-interleave\-sectors SECTORS"
-The number of interleaved sectors.
-.TP
-.B "\-\-integrity\-recalculate"
-Automatically recalculate integrity tags in kernel on activation.
-The device can be used during automatic integrity recalculation but becomes fully
-integrity protected only after the background operation is finished.
-This option is available since the Linux kernel version 4.19.
-.TP
-.B "\-\-integrity\-recalculate\-reset"
-Restart recalculation from the beginning of the device.
-It can be used to change the integrity checksum function.
-Note it does not change the tag length.
-This option is available since the Linux kernel version 5.13.
-.TP
-.B "\-\-journal\-watermark PERCENT"
-Journal watermark in percents. When the size of the journal exceeds this watermark,
-the journal flush will be started.
-.TP
-.B "\-\-journal\-commit\-time MS"
-Commit time in milliseconds. When this time passes (and no explicit flush operation was issued),
-the journal is written.
-.TP
-.B "\-\-tag\-size, \-t BYTES"
-Size of the integrity tag per-sector (here the integrity function will store authentication tag).
-
-\fBNOTE:\fR The size can be smaller that output size of the hash function, in that case only
-part of the hash will be stored.
-.TP
-.B "\-\-data\-device <data_device>"
-Specify a separate data device that contains existing data. The <device> then will contain
-calculated integrity tags and journal for data on <data_device>.
-
-\fBNOTE:\fR To not wipe the data device after initial format, also specify \-\-no-wipe option
-and activate with \-\-integrity-recalculate to automatically recalculate integrity tags.
-.TP
-.B "\-\-sector\-size, \-s BYTES"
-Sector size (power of two: 512, 1024, 2048, 4096).
-.TP
-.B "\-\-buffer\-sectors SECTORS"
-The number of sectors in one buffer.
-
-The tag area is accessed using buffers, the large buffer size means that the I/O size will
-be larger, but there could be less I/Os issued.
-.TP
-.B "\-\-integrity, \-I ALGORITHM"
-Use internal integrity calculation (standalone mode).
-The integrity algorithm can be CRC (crc32c/crc32), non-cryptographic hash function (xxhash64) or hash function (sha1, sha256).
-
-For HMAC (hmac-sha256) you have also to specify an integrity key and its size.
-.TP
-.B "\-\-integrity\-key\-size BYTES"
-The size of the data integrity key. Maximum is 4096 bytes.
-.TP
-.B "\-\-integrity\-key\-file FILE"
-The file with the integrity key.
-.TP
-.B "\-\-integrity\-no\-journal, \-D"
-Disable journal for integrity device.
-.TP
-.B "\-\-integrity\-bitmap\-mode. \-B"
-Use alternate bitmap mode (available since Linux kernel 5.2)  where dm-integrity uses bitmap
-instead of a journal. If a bit in the bitmap is 1, the corresponding region's data and integrity tags
-are not synchronized - if the machine crashes, the unsynchronized regions will be recalculated.
-The bitmap mode is faster than the journal mode, because we don't have to write the data
-twice, but it is also less reliable, because if data corruption happens
-when the machine crashes, it may not be detected.
-.TP
-.B "\-\-bitmap\-sectors\-per\-bit SECTORS"
-Number of 512-byte sectors per bitmap bit, the value must be power of two.
-.TP
-.B "\-\-bitmap\-flush\-time MS"
-Bitmap flush time in milliseconds.
-.TP
-
-\fBWARNING:\fR
-In case of a crash, it is possible that the data and integrity tag doesn't match
-if the journal is disabled.
-.TP
-.B "\-\-integrity\-recovery\-mode. \-R"
-Recovery mode (no journal, no tag checking).
-.TP
-
-\fBNOTE:\fR The following options are intended for testing purposes only.
-Using journal encryption does not make sense without encryption the data,
-these options are internally used in authenticated disk encryption with \fBcryptsetup(8)\fR.
-.TP
-.B "\-\-journal\-integrity ALGORITHM"
-Integrity algorithm for journal area.
-See \-\-integrity option for detailed specification.
-.TP
-.B "\-\-journal\-integrity\-key\-size BYTES"
-The size of the journal integrity key. Maximum is 4096 bytes.
-.TP
-.B "\-\-journal\-integrity\-key\-file FILE"
-The file with the integrity key.
-.TP
-.B "\-\-journal\-crypt ALGORITHM"
-Encryption algorithm for journal data area.
-You can use a block cipher here such as cbc-aes or
-a stream cipher, for example, chacha20 or ctr-aes.
-.TP
-.B "\-\-journal\-crypt\-key\-size BYTES"
-The size of the journal encryption key. Maximum is 4096 bytes.
-.TP
-.B "\-\-journal\-crypt\-key\-file FILE"
-The file with the journal encryption key.
-.TP
-.B "\-\-allow\-discards\fR"
-Allow the use of discard (TRIM) requests for the device.
-This option is available since the Linux kernel version 5.7.
-.TP
-.B "\-\-deferred"
-Defers device removal in \fIclose\fR command until the last user closes it.
-.TP
-.B "\-\-cancel\-deferred"
-Removes a previously configured deferred device removal in \fIclose\fR command.
-.TP
-The dm-integrity target is available since Linux kernel version 4.12.
-.TP
-\fBNOTE:\fR
-Format and activation of an integrity device always require superuser
-privilege because the superblock is calculated and handled in dm-integrity kernel target.
-
-.SH LEGACY COMPATIBILITY OPTIONS
-.TP
-\fBWARNING:\fR
-Do not use these options until you need compatibility with specific old kernel.
-.TP
-.B "\-\-integrity\-legacy\-padding"
-Use inefficient legacy padding.
-.TP
-.B "\-\-integrity\-legacy\-hmac"
-Use old flawed HMAC calculation (also does not protect superblock).
-.TP
-.B "\-\-integrity\-legacy\-recalculate"
-Allow insecure recalculating of volumes with HMAC keys (recalculation offset in superblock
-is not protected).
-
-.SH RETURN CODES
-Integritysetup returns 0 on success and a non-zero value on error.
-
-Error codes are:
-    1 wrong parameters
-    2 no permission
-    3 out of memory
-    4 wrong device specified
-    5 device already exists, or device is busy.
-
-.SH EXAMPLES
-Format the device with default standalone mode (CRC32C):
-
-.B "integritysetup format <device>"
-
-Open the device with default parameters:
-
-.B "integritysetup open <device> test"
-
-Format the device in standalone mode for use with HMAC(SHA256):
-
-.B "integritysetup format <device> \-\-tag\-size 32 \-\-integrity hmac\-sha256 \
-\-\-integrity\-key\-file <keyfile> \-\-integrity\-key\-size <key_bytes>"
-
-Open (activate) the device with HMAC(SHA256) and HMAC key in file:
-
-.B "integritysetup open <device> test \-\-integrity hmac\-sha256 \
-\-\-integrity\-key\-file <keyfile> \-\-integrity\-key\-size <key_bytes>"
-
-Dump dm-integrity superblock information:
-
-.B "integritysetup dump <device>"
-
-.SH REPORTING BUGS
-Report bugs, including ones in the documentation, on
-the cryptsetup mailing list at <cryptsetup@lists.linux.dev>
-or in the 'Issues' section on LUKS website.
-Please attach the output of the failed command with the
-\-\-debug option added.
-.SH AUTHORS
-The integritysetup tool is written by Milan Broz <gmazyland@gmail.com>
-and is part of the cryptsetup project.
-.SH COPYRIGHT
-Copyright \(co 2016-2022 Red Hat, Inc.
-.br
-Copyright \(co 2016-2022 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.
-.SH SEE ALSO
-The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR
-
-The integrity on-disk format specification available at
-\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity\fR

man/integritysetup.8.adoc

@@ -0,0 +1,334 @@
+= integritysetup(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: integritysetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+
+== NAME
+
+integritysetup - manage dm-integrity (block level integrity) volumes
+
+== SYNOPSIS
+
+*integritysetup <action> [<options>] <action args>*
+
+== DESCRIPTION
+
+Integritysetup is used to configure dm-integrity managed device-mapper
+mappings.
+
+Device-mapper integrity target provides read-write transparent integrity
+checking of block devices. The dm-integrity target emulates an additional
+data integrity field per-sector. You can use this additional field
+directly with integritysetup utility, or indirectly (for authenticated
+encryption) through cryptsetup.
+
+== BASIC ACTIONS
+
+Integritysetup supports these operations:
+
+=== FORMAT
+*format <device>*
+
+Formats <device> (calculates space and dm-integrity superblock and wipes
+the device).
+
+*<options>* can be [--data-device, --batch-mode, --no-wipe,
+--journal-size, --interleave-sectors, --tag-size, --integrity,
+--integrity-key-size, --integrity-key-file, --sector-size,
+--progress-frequency, --progress-json]
+
+=== OPEN
+*open <device> <name>* +
+create <name> <device> (*OBSOLETE syntax*)
+
+Open a mapping with <name> backed by device <device>.
+
+*<options>* can be [--data-device, --batch-mode, --journal-watermark,
+--journal-commit-time, --buffer-sectors, --integrity,
+--integrity-key-size, --integrity-key-file, --integrity-no-journal,
+--integrity-recalculate,
+--integrity-recalculate-reset,--integrity-recovery-mode,
+--allow-discards]
+
+=== CLOSE
+*close <name>* +
+remove <name> (*OBSOLETE syntax*)
+
+Removes existing mapping <name>.
+
+*<options>* can be [--deferred] or [--cancel-deferred]
+
+=== STATUS
+*status <name>*
+
+Reports status for the active integrity mapping <name>.
+
+=== DUMP
+*dump <device>*
+
+Reports parameters from on-disk stored superblock.
+
+=== RESIZE
+*resize <name>*
+
+Resizes an active mapping <name>.
+
+If --size (in 512-bytes sectors) or --device-size are not specified, the
+size is computed from the underlying device. After resize, the
+*recalculating* flag is set. If --wipe flag is set and the size of the
+device is increased, the newly added section will be wiped.
+
+Increasing the size of integrity volumes is available since the Linux
+kernel version 5.7, shrinking should work on older kernels too.
+
+*<options>* can be [--size, --device-size, --wipe]
+
+== OPTIONS
+*--progress-frequency <seconds>*::
+Print separate line every <seconds> with wipe progress.
+
+*--progress-json*::
+Prints wipe 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
+wipe progress (except it's compact single line):
++
+....
+{
+  "device":"/dev/sda"       // backing device or file
+  "device_bytes":"8192",    // bytes wiped so far
+  "device_size":"44040192", // total bytes to wipe
+  "speed":"126877696",      // calculated speed in bytes per second (based on progress so far)
+  "eta_ms":"2520012"        // estimated time to finish wipe in milliseconds
+  "time_ms":"5561235"       // total time spent wiping device 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.
+
+*--no-wipe*::
+Do not wipe the device after format. A device that is not initially
+wiped will contain invalid checksums.
+
+*--wipe*::
+Wipe the newly allocated area after resize to bigger size. If this
+flag is not set, checksums will be calculated for the data previously
+stored in the newly allocated area.
+
+*--journal-size, -j BYTES*::
+Size of the journal.
+
+*--interleave-sectors SECTORS*::
+The number of interleaved sectors.
+
+*--integrity-recalculate*::
+Automatically recalculate integrity tags in kernel on activation. The
+device can be used during automatic integrity recalculation but
+becomes fully integrity protected only after the background operation
+is finished. This option is available since the Linux kernel version
+4.19.
+
+*--integrity-recalculate-reset*::
+Restart recalculation from the beginning of the device. It can be used
+to change the integrity checksum function. Note it does not change the
+tag length. This option is available since the Linux kernel version
+5.13.
+
+*--journal-watermark PERCENT*::
+Journal watermark in percents. When the size of the journal exceeds
+this watermark, the journal flush will be started.
+
+*--journal-commit-time MS*::
+Commit time in milliseconds. When this time passes (and no explicit
+flush operation was issued), the journal is written.
+
+*--tag-size, -t BYTES*::
+Size of the integrity tag per-sector (here the integrity function will
+store authentication tag).
++
+*NOTE:* The size can be smaller that output size of the hash function,
+in that case only part of the hash will be stored.
+
+*--data-device <data_device>*::
+Specify a separate data device that contains existing data. The
+<device> then will contain calculated integrity tags and journal for
+data on <data_device>.
++
+*NOTE:* To not wipe the data device after initial format, also specify
+--no-wipe option and activate with --integrity-recalculate to
+automatically recalculate integrity tags.
+
+*--sector-size, -s BYTES*::
+Sector size (power of two: 512, 1024, 2048, 4096).
+
+*--buffer-sectors SECTORS*::
+The number of sectors in one buffer.
++
+The tag area is accessed using buffers, the large buffer size means that
+the I/O size will be larger, but there could be less I/Os issued.
+
+*--integrity, -I ALGORITHM*::
+Use internal integrity calculation (standalone mode). The integrity
+algorithm can be CRC (crc32c/crc32), non-cryptographic hash function
+(xxhash64) or hash function (sha1, sha256).
++
+For HMAC (hmac-sha256) you have also to specify an integrity key and its
+size.
+
+*--integrity-key-size BYTES*::
+The size of the data integrity key. Maximum is 4096 bytes.
+
+*--integrity-key-file FILE*::
+The file with the integrity key.
+
+*--integrity-no-journal, -D*::
+Disable journal for integrity device.
+
+*--integrity-bitmap-mode. -B*::
+Use alternate bitmap mode (available since Linux kernel 5.2) where
+dm-integrity uses bitmap instead of a journal. If a bit in the bitmap
+is 1, the corresponding region's data and integrity tags are not
+synchronized - if the machine crashes, the unsynchronized regions will
+be recalculated. The bitmap mode is faster than the journal mode,
+because we don't have to write the data twice, but it is also less
+reliable, because if data corruption happens when the machine crashes,
+it may not be detected.
+
+*--bitmap-sectors-per-bit SECTORS*::
+Number of 512-byte sectors per bitmap bit, the value must be power of
+two.
+
+*--bitmap-flush-time MS*::
+Bitmap flush time in milliseconds.
++
+*WARNING:*::
+In case of a crash, it is possible that the data and integrity tag
+doesn't match if the journal is disabled.
+
+*--integrity-recovery-mode. -R*::
+Recovery mode (no journal, no tag checking).
+
+*NOTE:* The following options are intended for testing purposes only.:
+Using journal encryption does not make sense without encryption the
+data, these options are internally used in authenticated disk
+encryption with *cryptsetup(8)*.
+
+*--journal-integrity ALGORITHM*::
+Integrity algorithm for journal area. See --integrity option for
+detailed specification.
+
+*--journal-integrity-key-size BYTES*::
+The size of the journal integrity key. Maximum is 4096 bytes.
+
+*--journal-integrity-key-file FILE*::
+The file with the integrity key.
+
+*--journal-crypt ALGORITHM*::
+Encryption algorithm for journal data area. You can use a block cipher
+here such as cbc-aes or a stream cipher, for example, chacha20 or
+ctr-aes.
+
+*--journal-crypt-key-size BYTES*::
+The size of the journal encryption key. Maximum is 4096 bytes.
+
+*--journal-crypt-key-file FILE*::
+The file with the journal encryption key.
+
+*--allow-discards*::
+Allow the use of discard (TRIM) requests for the device. This option
+is available since the Linux kernel version 5.7.
+
+*--deferred*::
+Defers device removal in *close* command until the last user closes
+it.
+
+*--cancel-deferred*::
+Removes a previously configured deferred device removal in *close*
+command.
+
+*--verbose, -v*::
+Print more information on command execution.
+
+*--debug*::
+Run in debug mode with full diagnostic logs. Debug output lines are
+always prefixed by *#*.
+
+*--version, -V*::
+Show the program version.
+
+*--batch-mode, -q*::
+Do not ask for confirmation.
+
+*--usage*::
+Show short option help.
+
+*--help, -?*::
+Show help text and default parameters.
+
+== LEGACY COMPATIBILITY OPTIONS
+
+*WARNING:*::
+Do not use these options until you need compatibility with specific
+old kernel.
+
+*--integrity-legacy-padding*::
+Use inefficient legacy padding.
+
+*--integrity-legacy-hmac*::
+Use old flawed HMAC calculation (also does not protect superblock).
+
+*--integrity-legacy-recalculate*::
+Allow insecure recalculating of volumes with HMAC keys (recalculation
+offset in superblock is not protected).
+
+== RETURN CODES
+
+Integritysetup returns *0* on success and a non-zero value on error.
+
+Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory,
+*4* wrong device specified, *5* device already exists or device is busy.
+
+== NOTES
+The dm-integrity target is available since Linux kernel version 4.12.
+
+Format and activation of an integrity device always require superuser
+privilege because the superblock is calculated and handled in
+dm-integrity kernel target.
+
+== EXAMPLES
+
+Format the device with default standalone mode (CRC32C):
+
+*integritysetup format <device>*
+
+Open the device with default parameters:
+
+*integritysetup open <device> test*
+
+Format the device in standalone mode for use with HMAC(SHA256):
+
+*integritysetup format <device> --tag-size 32 --integrity hmac-sha256
+--integrity-key-file <keyfile> --integrity-key-size <key_bytes>*
+
+Open (activate) the device with HMAC(SHA256) and HMAC key in file:
+
+*integritysetup open <device> test --integrity hmac-sha256
+--integrity-key-file <keyfile> --integrity-key-size <key_bytes>*
+
+Dump dm-integrity superblock information:
+
+*integritysetup dump <device>*
+
+== DM-INTEGRITY ON-DISK FORMAT
+
+The on-disk format specification available at
+https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity[*DMIntegrity*] page.
+
+== AUTHORS
+
+The integritysetup tool is written by mailto:gmazyland@gmail.com[Milan Broz].
+
+include::man/common_footer.adoc[]

man/veritysetup.8

@@ -1,278 +0,0 @@
-.TH VERITYSETUP "8" "January 2021" "veritysetup" "Maintenance Commands"
-.SH NAME
-veritysetup - manage dm-verity (block level verification) volumes
-.SH SYNOPSIS
-.B veritysetup <options> <action> <action args>
-.SH DESCRIPTION
-.PP
-Veritysetup is used to configure dm-verity managed device-mapper mappings.
-
-Device-mapper verity target provides read-only transparent integrity
-checking of block devices using kernel crypto API.
-
-The dm-verity devices are always read-only.
-
-Veritysetup supports these operations:
-.PP
-\fIformat\fR <data_device> <hash_device>
-.IP
-Calculates and permanently stores hash verification data for data_device.
-Hash area can be located on the same device after data if specified
-by \-\-hash\-offset option.
-
-Note you need to provide root hash string for device verification
-or activation. Root hash must be trusted.
-
-The data or hash device argument can be block device or file image.
-If hash device path doesn't exist, it will be created as file.
-
-\fB<options>\fR can be [\-\-hash, \-\-no-superblock, \-\-format,
-\-\-data-block-size, \-\-hash-block-size, \-\-data-blocks, \-\-hash-offset,
-\-\-salt, \-\-uuid, \-\-root-hash-file]
-
-If option \-\-root-hash-file is used, the root hash is stored in hex-encoded text
-format in <path>.
-.PP
-\fIopen\fR <data_device> <name> <hash_device> <root_hash>
-.br
-\fIopen\fR <data_device> <name> <hash_device> \-\-root-hash-file <path>
-.br
-\fIcreate\fR <name> <data_device> <hash_device> <root_hash>  (\fBOBSOLETE syntax\fR)
-.IP
-Creates a mapping with <name> backed by device <data_device> and using
-<hash_device> for in-kernel verification.
-
-The <root_hash> is a hexadecimal string.
-
-\fB<options>\fR can be [\-\-hash-offset, \-\-no-superblock,
-\-\-ignore-corruption or \-\-restart-on-corruption, \-\-panic-on-corruption,
-\-\-ignore-zero-blocks, \-\-check-at-most-once, \-\-root-hash-signature,
-\-\-root-hash-file]
-
-If option \-\-root-hash-file is used, the root hash is read from <path> instead
-of from the command line parameter. Expects hex-encoded text, without terminating
-newline.
-
-If option \-\-no-superblock is used, you have to use as the same options
-as in initial format operation.
-.PP
-\fIverify\fR <data_device> <hash_device> <root_hash>
-.br
-\fIverify\fR <data_device> <hash_device> \-\-root-hash-file <path>
-.IP
-Verifies data on data_device with use of hash blocks stored on hash_device.
-
-This command performs userspace verification, no kernel device is created.
-
-The <root_hash> is a hexadecimal string.
-
-If option \-\-root-hash-file is used, the root hash is read from <path> instead
-of from the command line parameter. Expects hex-encoded text, without terminating
-newline.
-
-\fB<options>\fR can be [\-\-hash-offset, \-\-no-superblock, \-\-root-hash-file]
-
-If option \-\-no-superblock is used, you have to use as the same options
-as in initial format operation.
-.PP
-\fIclose\fR <name>
-.IP
-Removes existing mapping <name>.
-
-For backward compatibility there is \fBremove\fR command alias
-for \fBclose\fR command.
-
-\fB<options>\fR can be [\-\-deferred] or [\-\-cancel\-deferred]
-
-.PP
-\fIstatus\fR <name>
-.IP
-Reports status for the active verity mapping <name>.
-.PP
-\fIdump\fR <hash_device>
-.IP
-Reports parameters of verity device from on-disk stored superblock.
-
-\fB<options>\fR can be [\-\-hash-offset]
-.SH OPTIONS
-.TP
-.B "\-\-verbose, \-v"
-Print more information on command execution.
-.TP
-.B "\-\-debug"
-Run in debug mode with full diagnostic logs. Debug output
-lines are always prefixed by '#'.
-.TP
-.B "\-\-no-superblock"
-Create or use dm-verity without permanent on-disk superblock.
-.TP
-.B "\-\-format=number"
-Specifies the hash version type.
-Format type 0 is original Chrome OS version. Format type 1 is current version.
-.TP
-.B "\-\-data-block-size=bytes"
-Used block size for the data device.
-(Note kernel supports only page-size as maximum here.)
-.TP
-.B "\-\-hash-block-size=bytes"
-Used block size for the hash device.
-(Note kernel supports only page-size as maximum here.)
-.TP
-.B "\-\-data-blocks=blocks"
-Size of data device used in verification.
-If not specified, the whole device is used.
-.TP
-.B "\-\-hash-offset=bytes"
-Offset of hash area/superblock on hash_device.
-Value must be aligned to disk sector offset.
-.TP
-.B "\-\-salt=hex string"
-Salt used for format or verification.
-Format is a hexadecimal string.
-.TP
-.B "\-\-uuid=UUID"
-Use the provided UUID for format command instead of generating new one.
-
-The UUID must be provided in standard UUID format,
-e.g. 12345678-1234-1234-1234-123456789abc.
-.TP
-.B "\-\-ignore-corruption", "\-\-restart-on-corruption", "\-\-panic-on-corruption"
-Defines what to do if data integrity problem is detected (data corruption).
-
-Without these options kernel fails the IO operation with I/O error.
-With \-\-ignore-corruption option the corruption is only logged.
-With \-\-restart-on-corruption or  \-\-panic-on-corruption the kernel
-is restarted (panicked) immediately.
-(You have to provide way how to avoid restart loops.)
-
-\fBWARNING:\fR Use these options only for very specific cases.
-These options are available since Linux kernel version 4.1.
-.TP
-.B "\-\-ignore-zero-blocks"
-Instruct kernel to not verify blocks that are expected to contain zeroes
-and always directly return zeroes instead.
-
-\fBWARNING:\fR Use this option only in very specific cases.
-This option is available since Linux kernel version 4.5.
-.TP
-.B "\-\-check-at-most-once"
-Instruct kernel to verify blocks only the first time they are read
-from the data device, rather than every time.
-
-\fBWARNING:\fR It provides a reduced level of security because only
-offline tampering of the data device's content will be detected,
-not online tampering.
-This option is available since Linux kernel version 4.17.
-.TP
-.B "\-\-hash=hash"
-Hash algorithm for dm-verity. For default see \-\-help option.
-.TP
-.B "\-\-version"
-Show the program version.
-.TP
-.B "\-\-fec-device=fec_device"
-Use forward error correction (FEC) to recover from corruption if hash verification fails.
-Use encoding data from the specified device.
-
-The fec device argument can be block device or file image.
-For format, if fec device path doesn't exist, it will be created as file.
-
-Block sizes for data and hash devices must match.
-Also, if the verity data_device is encrypted the fec_device should be too.
-
-FEC calculation covers data, hash area, and optional foreign metadata stored on the same
-device with the hash tree (additional space after hash area).
-Size of this optional additional area protected by FEC is calculated from image sizes,
-so you must be sure that you use the same images for activation.
-
-If the hash device is in a separate image, metadata covers the whole rest of the image after the hash area.
-
-If hash and FEC device is in the image, metadata ends on the FEC area offset.
-
-.TP
-.B "\-\-fec-offset=bytes"
-This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding data.
-.TP
-.B "\-\-fec-roots=num"
-Number of generator roots. This equals to the number of parity bytes in the encoding data.
-In RS(M, N) encoding, the number of roots is M-N. M is 255 and M-N is between 2 and 24 (including).
-.TP
-.B "\-\-root-hash-file=FILE"
-Path to file with stored root hash in hex-encoded text.
-.TP
-.B "\-\-root-hash-signature=FILE"
-Path to roothash signature file used to verify the root hash (in kernel).
-This feature requires Linux kernel version 5.4 or more recent.
-.TP
-.B "\-\-deferred"
-Defers device removal in \fIclose\fR command until the last user closes it.
-.TP
-.B "\-\-cancel\-deferred"
-Removes a previously configured deferred device removal in \fIclose\fR command.
-.TP
-.SH RETURN CODES
-Veritysetup returns 0 on success and a non-zero value on error.
-
-Error codes are:
-    1 wrong parameters
-    2 no permission
-    3 out of memory
-    4 wrong device specified
-    5 device already exists or device is busy.
-
-.SH EXAMPLES
-.B "veritysetup \-\-data-blocks=256 format <data_device> <hash_device>"
-
-Calculates and stores verification data on hash_device for the first 256 blocks (of block-size).
-If hash_device does not exist, it is created (as file image).
-
-.B "veritysetup format --root-hash-file <path> <data_device> <hash_device>"
-
-Calculates and stores verification data on hash_device for the whole data_device, and store the
-root hash as hex-encoded text in <path>.
-
-.B "veritysetup \-\-data-blocks=256 \-\-hash-offset=1052672 format <device> <device>"
-
-Verification data (hashes) is stored on the same device as data (starting at hash-offset).
-Hash-offset must be greater than number of blocks in data-area.
-
-.B "veritysetup \-\-data-blocks=256 \-\-hash-offset=1052672 create test-device <device> <device> <root_hash>"
-
-Activates the verity device named test-device. Options \-\-data-blocks and \-\-hash-offset are the same
-as in the format command. The <root_hash> was calculated in format command.
-
-.B "veritysetup \-\-data-blocks=256 \-\-hash-offset=1052672 verify <data_device> <hash_device> <root_hash>"
-
-Verifies device without activation (in userspace).
-
-.B "veritysetup \-\-data-blocks=256 \-\-hash-offset=1052672 --root-hash-file <path> verify <data_device> <hash_device>"
-
-Verifies device without activation (in userspace). Root hash passed via a file rather than inline.
-
-.B "veritysetup \-\-fec-device=<fec_device> \-\-fec-roots=10 format <data_device> <hash_device>"
-
-Calculates and stores verification and encoding data for data_device.
-
-.SH REPORTING BUGS
-Report bugs, including ones in the documentation, on
-the cryptsetup mailing list at <cryptsetup@lists.linux.dev>
-or in the 'Issues' section on LUKS website.
-Please attach the output of the failed command with the
-\-\-debug option added.
-.SH AUTHORS
-The first implementation of veritysetup was written by Chrome OS authors.
-
-This version is based on verification code written by Mikulas Patocka <mpatocka@redhat.com>
-and rewritten for libcryptsetup by Milan Broz <gmazyland@gmail.com>.
-.SH COPYRIGHT
-Copyright \(co 2012-2022 Red Hat, Inc.
-.br
-Copyright \(co 2012-2022 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.
-.SH SEE ALSO
-The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR
-
-The verity on-disk format specification available at
-\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity\fR

man/veritysetup.8.adoc

@@ -0,0 +1,307 @@
+= veritysetup(8)
+:doctype: manpage
+:manmanual: Maintenance Commands
+:mansource: veritysetup {release-version}
+:man-linkstyle: pass:[blue R < >]
+
+== NAME
+
+veritysetup - manage dm-verity (block level verification) volumes
+
+== SYNOPSIS
+
+*veritysetup <action> [<options>] <action args>*
+
+== DESCRIPTION
+
+Veritysetup is used to configure dm-verity managed device-mapper
+mappings.
+
+Device-mapper verity target provides read-only transparent integrity
+checking of block devices using kernel crypto API.
+
+The dm-verity devices are always read-only.
+
+== BASIC ACTIONS
+
+Veritysetup supports these operations:
+
+=== FORMAT
+*format <data_device> <hash_device>*
+
+Calculates and permanently stores hash verification data for
+data_device. Hash area can be located on the same device after data if
+specified by --hash-offset option.
+
+Note you need to provide root hash string for device verification or
+activation. Root hash must be trusted.
+
+The data or hash device argument can be block device or file image. If
+hash device path doesn't exist, it will be created as file.
+
+*<options>* can be [--hash, --no-superblock, --format,
+--data-block-size, --hash-block-size, --data-blocks, --hash-offset,
+--salt, --uuid, --root-hash-file]
+
+If option --root-hash-file is used, the root hash is stored in
+hex-encoded text format in <path>.
+
+=== OPEN
+*open <data_device> <name> <hash_device> <root_hash>* +
+*open <data_device> <name> <hash_device> --root-hash-file <path>* +
+create <name> <data_device> <hash_device> <root_hash> (*OBSOLETE syntax*)
+
+Creates a mapping with <name> backed by device <data_device> and using
+<hash_device> for in-kernel verification.
+
+The <root_hash> is a hexadecimal string.
+
+*<options>* can be [--hash-offset, --no-superblock, --ignore-corruption
+or --restart-on-corruption, --panic-on-corruption, --ignore-zero-blocks,
+--check-at-most-once, --root-hash-signature, --root-hash-file]
+
+If option --root-hash-file is used, the root hash is read from <path>
+instead of from the command line parameter. Expects hex-encoded text,
+without terminating newline.
+
+If option --no-superblock is used, you have to use as the same options
+as in initial format operation.
+
+=== VERIFY
+*verify <data_device> <hash_device> <root_hash>* +
+*verify <data_device> <hash_device> --root-hash-file <path>*
+
+Verifies data on data_device with use of hash blocks stored on
+hash_device.
+
+This command performs userspace verification, no kernel device is
+created.
+
+The <root_hash> is a hexadecimal string.
+
+If option --root-hash-file is used, the root hash is read from <path>
+instead of from the command line parameter. Expects hex-encoded text,
+without terminating newline.
+
+*<options>* can be [--hash-offset, --no-superblock, --root-hash-file]
+
+If option --no-superblock is used, you have to use as the same options
+as in initial format operation.
+
+=== CLOSE
+*close <name>* +
+remove <name> (*OBSOLETE syntax*)
+
+Removes existing mapping <name>.
+
+*<options>* can be [--deferred] or [--cancel-deferred]
+
+=== STATUS
+*status <name>*
+
+Reports status for the active verity mapping <name>.
+
+=== DUMP
+*dump <hash_device>*
+
+Reports parameters of verity device from on-disk stored superblock.
+
+*<options>* can be [--hash-offset]
+
+== OPTIONS
+
+*--no-superblock*::
+Create or use dm-verity without permanent on-disk superblock.
+
+*--format=number*::
+Specifies the hash version type. Format type 0 is original Chrome OS
+version. Format type 1 is current version.
+
+*--data-block-size=bytes*::
+Used block size for the data device. (Note kernel supports only
+page-size as maximum here.)
+
+*--hash-block-size=bytes*::
+Used block size for the hash device. (Note kernel supports only
+page-size as maximum here.)
+
+*--data-blocks=blocks*::
+Size of data device used in verification. If not specified, the whole
+device is used.
+
+*--hash-offset=bytes*::
+Offset of hash area/superblock on hash_device. Value must be aligned
+to disk sector offset.
+
+*--salt=hex string*::
+Salt used for format or verification. Format is a hexadecimal string.
+
+*--uuid=UUID*::
+Use the provided UUID for format command instead of generating new
+one.
++
+The UUID must be provided in standard UUID format, e.g.
+12345678-1234-1234-1234-123456789abc.
+*--ignore-corruption , --restart-on-corruption ,
+--panic-on-corruption*::
+Defines what to do if data integrity problem is detected (data
+corruption).
++
+Without these options kernel fails the IO operation with I/O error. With
+--ignore-corruption option the corruption is only logged. With
+--restart-on-corruption or --panic-on-corruption the kernel is restarted
+(panicked) immediately. (You have to provide way how to avoid restart
+loops.)
++
+*WARNING:* Use these options only for very specific cases. These options
+are available since Linux kernel version 4.1.
+
+*--ignore-zero-blocks*::
+Instruct kernel to not verify blocks that are expected to contain
+zeroes and always directly return zeroes instead.
++
+*WARNING:* Use this option only in very specific cases. This option is
+available since Linux kernel version 4.5.
+
+*--check-at-most-once*::
+Instruct kernel to verify blocks only the first time they are read
+from the data device, rather than every time.
++
+*WARNING:* It provides a reduced level of security because only offline
+tampering of the data device's content will be detected, not online
+tampering. This option is available since Linux kernel version 4.17.
+
+*--hash=hash*::
+Hash algorithm for dm-verity. For default see --help option.
+
+*--fec-device=fec_device*::
+Use forward error correction (FEC) to recover from corruption if hash
+verification fails. Use encoding data from the specified device.
++
+The fec device argument can be block device or file image. For format,
+if fec device path doesn't exist, it will be created as file.
++
+Block sizes for data and hash devices must match. Also, if the verity
+data_device is encrypted the fec_device should be too.
++
+FEC calculation covers data, hash area, and optional foreign metadata
+stored on the same device with the hash tree (additional space after
+hash area). Size of this optional additional area protected by FEC is
+calculated from image sizes, so you must be sure that you use the same
+images for activation.
++
+If the hash device is in a separate image, metadata covers the whole
+rest of the image after the hash area.
++
+If hash and FEC device is in the image, metadata ends on the FEC area
+offset.
+
+*--fec-offset=bytes*::
+This is the offset, in bytes, from the start of the FEC device to the
+beginning of the encoding data.
+
+*--fec-roots=num*::
+Number of generator roots. This equals to the number of parity bytes
+in the encoding data. In RS(M, N) encoding, the number of roots is
+M-N. M is 255 and M-N is between 2 and 24 (including).
+
+*--root-hash-file=FILE*::
+Path to file with stored root hash in hex-encoded text.
+
+*--root-hash-signature=FILE*::
+Path to root hash signature file used to verify the root hash (in
+kernel). This feature requires Linux kernel version 5.4 or more
+recent.
+
+*--deferred*::
+Defers device removal in *close* command until the last user closes
+it.
+
+*--cancel-deferred*::
+Removes a previously configured deferred device removal in *close*
+command.
+
+*--verbose, -v*::
+Print more information on command execution.
+
+*--debug*::
+Run in debug mode with full diagnostic logs. Debug output lines are
+always prefixed by *#*.
+
+*--version, -V*::
+Show the program version.
+
+*--batch-mode, -q*::
+Do not ask for confirmation.
+
+*--usage*::
+Show short option help.
+
+*--help, -?*::
+Show help text and default parameters.
+
+== RETURN CODES
+
+Veritysetup returns *0* on success and a non-zero value on error.
+
+Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory,
+*4* wrong device specified, *5* device already exists or device is busy.
+
+== EXAMPLES
+
+*veritysetup --data-blocks=256 format <data_device> <hash_device>*
+
+Calculates and stores verification data on hash_device for the first 256
+blocks (of block-size). If hash_device does not exist, it is created (as
+file image).
+
+*veritysetup format --root-hash-file <path> <data_device> <hash_device>*
+
+Calculates and stores verification data on hash_device for the whole
+data_device, and store the root hash as hex-encoded text in <path>.
+
+*veritysetup --data-blocks=256 --hash-offset=1052672 format <device>
+<device>*
+
+Verification data (hashes) is stored on the same device as data
+(starting at hash-offset). Hash-offset must be greater than number of
+blocks in data-area.
+
+*veritysetup --data-blocks=256 --hash-offset=1052672 create test-device
+<device> <device> <root_hash>*
+
+Activates the verity device named test-device. Options --data-blocks and
+--hash-offset are the same as in the format command. The <root_hash> was
+calculated in format command.
+
+*veritysetup --data-blocks=256 --hash-offset=1052672 verify
+<data_device> <hash_device> <root_hash>*
+
+Verifies device without activation (in userspace).
+
+*veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file
+<path> verify <data_device> <hash_device>*
+
+Verifies device without activation (in userspace). Root hash passed via
+a file rather than inline.
+
+*veritysetup --fec-device=<fec_device> --fec-roots=10 format
+<data_device> <hash_device>*
+
+Calculates and stores verification and encoding data for data_device.
+
+== DM-VERITY ON-DISK SPECIFICATION
+
+The on-disk format specification is available at
+https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity[*DMVerity*] page.
+
+== AUTHORS
+
+The first implementation of veritysetup was written by Chrome OS
+authors.
+
+This version is based on verification code written by
+mailto:mpatocka@redhat.com[Mikulas Patocka] and rewritten for libcryptsetup
+by mailto:gmazyland@gmail.com[Milan Broz].
+
+include::man/common_footer.adoc[]