FM / cryptsetup

/usr/share/doc/cryptsetup

Name	Size	Mode	Actions
examples/	-	0755	rm
AUTHORS	137	0644	edit dl rm
changelog.Debian.gz	2251	0644	edit dl rm
copyright	9292	0644	edit dl rm
FAQ.gz	48990	0644	edit dl rm
Keyring.txt	2724	0644	edit dl rm
LUKS2-locking.txt	2711	0644	edit dl rm
NEWS.Debian.gz	1057	0644	edit dl rm
README.Debian.gz	5680	0644	edit dl rm
README.debug	2731	0644	edit dl rm
README.gnupg	1848	0644	edit dl rm
README.gnupg-sc	2354	0644	edit dl rm
README.keyctl	3583	0644	edit dl rm
README.md.gz	2223	0644	edit dl rm
README.opensc.gz	2219	0644	edit dl rm
v1.0.7-ReleaseNotes	2921	0644	edit dl rm
v1.1.0-ReleaseNotes.gz	2275	0644	edit dl rm
v1.1.1-ReleaseNotes	1796	0644	edit dl rm
v1.1.2-ReleaseNotes	1594	0644	edit dl rm
v1.1.3-ReleaseNotes	482	0644	edit dl rm
v1.2.0-ReleaseNotes.gz	2124	0644	edit dl rm
v1.3.0-ReleaseNotes.gz	2134	0644	edit dl rm
v1.3.1-ReleaseNotes	421	0644	edit dl rm
v1.4.0-ReleaseNotes.gz	2253	0644	edit dl rm
v1.4.1-ReleaseNotes	889	0644	edit dl rm
v1.4.2-ReleaseNotes	1630	0644	edit dl rm
v1.4.3-ReleaseNotes	2359	0644	edit dl rm
v1.5.0-ReleaseNotes.gz	3320	0644	edit dl rm
v1.5.1-ReleaseNotes	1295	0644	edit dl rm
v1.6.0-ReleaseNotes.gz	3818	0644	edit dl rm
v1.6.1-ReleaseNotes	1041	0644	edit dl rm
v1.6.2-ReleaseNotes	985	0644	edit dl rm
v1.6.3-ReleaseNotes	1859	0644	edit dl rm
v1.6.4-ReleaseNotes	2036	0644	edit dl rm
v1.6.5-ReleaseNotes	2479	0644	edit dl rm
v1.6.6-ReleaseNotes	1093	0644	edit dl rm
v1.6.7-ReleaseNotes	3333	0644	edit dl rm
v1.6.8-ReleaseNotes	2061	0644	edit dl rm
v1.7.0-ReleaseNotes	3101	0644	edit dl rm
v1.7.1-ReleaseNotes	1371	0644	edit dl rm
v1.7.2-ReleaseNotes	1487	0644	edit dl rm
v1.7.3-ReleaseNotes	811	0644	edit dl rm
v1.7.4-ReleaseNotes	657	0644	edit dl rm
v1.7.5-ReleaseNotes	833	0644	edit dl rm
v2.0.0-ReleaseNotes.gz	9728	0644	edit dl rm
v2.0.1-ReleaseNotes.gz	2226	0644	edit dl rm
v2.0.2-ReleaseNotes.gz	1992	0644	edit dl rm
v2.0.3-ReleaseNotes.gz	2448	0644	edit dl rm
v2.0.4-ReleaseNotes.gz	2325	0644	edit dl rm
v2.0.5-ReleaseNotes.gz	2068	0644	edit dl rm
v2.0.6-ReleaseNotes.gz	1960	0644	edit dl rm
v2.1.0-ReleaseNotes.gz	3484	0644	edit dl rm
v2.2.0-ReleaseNotes.gz	4582	0644	edit dl rm
v2.2.1-ReleaseNotes	1413	0644	edit dl rm
v2.2.2-ReleaseNotes	2151	0644	edit dl rm
v2.3.0-ReleaseNotes.gz	3250	0644	edit dl rm
v2.3.1-ReleaseNotes	1770	0644	edit dl rm
v2.3.2-ReleaseNotes	1499	0644	edit dl rm
v2.3.3-ReleaseNotes	1396	0644	edit dl rm
v2.3.4-ReleaseNotes.gz	2001	0644	edit dl rm
v2.3.5-ReleaseNotes.gz	3129	0644	edit dl rm
v2.3.6-ReleaseNotes	2316	0644	edit dl rm
v2.4.0-ReleaseNotes.gz	4766	0644	edit dl rm
v2.4.1-ReleaseNotes	1942	0644	edit dl rm
v2.4.2-ReleaseNotes	1375	0644	edit dl rm
v2.4.3-ReleaseNotes.gz	1996	0644	edit dl rm

Edit: /usr/share/doc/cryptsetup/README.debug (2731B)

Debugging Cryptsetup issues
===========================

Cryptsetup is responsible for unlocking dm-crypt devices. The cryptsetup Debian
provide a whole slew of helper scripts that integrate cryptsetup into the
Debian operating system. The most important ones are the `cryptdisks` init
script and the `cryptroot` initramfs scripts, both implementing support for the
`/etc/crypttab` configuration file and for automatic unlocking of encrypted
devices during the boot process.

This page collects information on debugging different features of the Debian
cryptsetup packages in case of problems.

Debug cryptroot initramfs script
--------------------------------

In order to debug the cryptroot initramfs script during initramfs stage, the
following steps are required:

* Boot into the initramfs rescue shell by adding `break=premount` as kernel
  option during boot

In grub, this can be done interactively from the grub boot menu: `<E>` to
  edit, and `<Ctrl>+<X>` to boot once you've edited the kernel line.

See <https://help.ubuntu.com/community/Grub2/Troubleshooting#Editing_the_GRUB_2_Menu_During_Boot>
  for details.

* Append `-x` to the shebang (first line) of cryptroot initramfs script:

sed -i -e '1s,^#!/bin/sh,& -x,' /scripts/local-top/cryptroot

* Run the cryptroot initramfs script manually, redirecting output to a log file:

/scripts/local-top/cryptroot 2>&1 | tee /run/initramfs/cryptroot.debug

**Please note:** if the boot process is broken, you might need to mount an
  external storage device (e.g. a USB flash drive) inside the initramfs and
  redirect the output to a log files on this external device.

* Continue the boot process (by pressing `<Ctrl>+<D>`) and save a copy of the
  debug log file to `/run/initramfs/cryptroot.debug`. The content of `/run/`
  will be lost after reboot.

Sometimes, debugging the initramfs directly can be helpful as well. See
<https://wiki.debian.org/InitramfsDebug#Saving_debug_information> for details.

Gather debugging information in the initramfs rescue shell
----------------------------------------------------------

Useful commands to gather information from initramfs rescue shell:

* Check for device-mapper support (these directories/symlinks exist only if
  kernel has device-mapper support):

ls -l /sys/class/misc/device-mapper /sys/devices/virtual/misc/device-mapper

* Check whether dm-crypt kernel module is loaded:

lsmod | grep dm-crypt

* Display cryptroot configuration and list loaded kernel modules:

cat /cryptroot/crypttab
      lsmod

* Gather information about the available block devices:

blkid
      ls -l /dev/disk/by-*/

-- Jonas Meurer <jonas@freesources.org>, Wed 25 Dec 2019 02:58:00 PM CET

cmd: