File Content: README.debug 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 Submit