Package: cryptsetup
Version: 2:2.6.1-4~deb12u2
Severity: minor
Tags: upstream
X-Debbugs-Cc: [email protected]
The cryptsetup-luksFormat man page contains:
===✂----------------------------------------
DESCRIPTION
…
To use specific version of LUKS format, use --type luks1 or type luks2.
…
OPTIONS
--type <device-type>
Specifies required device type, for more info read BASIC ACTIONS
section in cryptsetup(8).
===✂----------------------------------------
Man pages are most commonly used as a reference, so if someone wants
details on the --type option, they will generally skip the lengthy
DESCRIPTION and go straight to OPTIONS. But the arguments are not
documented there. Readers are referred to the top level “cryptsetup”
man page, which is likely where they came from. Revisiting the top
level man page shows a scattered variety of several different device
types, many of which do not apply to luksFormat. The BASIC ACTIONS
section is completely useless for getting details about the device
type.
So we return to cryptsetup-luksFormat to find that the args are
actually described in the DESCRIPTION section. From there, it does not
state what is the default setting.
The cryptsetup-luksFormat man page leaves us wondering what is the
difference. So then I went back to the top level man page which buries
it in a LUKS EXTENSION section (not BASIC ACTIONS).
There is more confusion in the cryptsetup-open man page, which has:
“Device type can be plain, luks (default), luks1, luks2, loopaes or tcrypt.”
How does “luks” differ from “luks1” and “luks2”? Is it safe to say
that is also the default for luksFormat? Also, why is BitLocker and
FileVault2 missing from the above quoted statement, but mentioned
further down the page?
There is merit to keeping the luks1/luks2 description in one place in
the top level, but redirects must be correct.
These changes would help:
- cryptsetup-luksFormat::OPTIONS::--type should at least enumerate the
possible arguments and indicate the default.
- cryptsetup-luksFormat::OPTIONS::--type should direct readers to the
top level LUKS EXTENSION section.
-- Package-specific info:
-- System Information:
Debian Release: 12.12
APT prefers oldstable-updates
APT policy: (990, 'oldstable-updates'), (990, 'oldstable-security'), (990,
'stable'), (990, 'oldstable'), (500, 'oldoldstable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386
Kernel: Linux 5.10.0-28-amd64 (SMP w/2 CPU threads)
Kernel taint flags: TAINT_OOT_MODULE, TAINT_UNSIGNED_MODULE
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
Versions of packages cryptsetup depends on:
ii cryptsetup-bin 2:2.6.1-4~deb12u2
ii debconf [debconf-2.0] 1.5.82
ii dmsetup 2:1.02.185-2
ii libc6 2.36-9+deb12u13
cryptsetup recommends no packages.
Versions of packages cryptsetup suggests:
ii cryptsetup-initramfs 2:2.6.1-4~deb12u2
ii dosfstools 4.2-1
pn keyutils <none>
ii liblocale-gettext-perl 1.07-5
-- debconf information:
cryptsetup/prerm_active_mappings: true
