Debian 13 Tutorial / Diagnose Boot Failures and Prepare initramfs and Rescue Recovery
Diagnose a Debian 13 boot failure by identifying the last working stage: firmware, bootloader, kernel, initial filesystem or systemd. Do not conclude a boot failure solely because SSH connection fails; you need to check the console, the actual root and boot partitions, and the installed kernel. This lecture explains how to create and inspect a separate initramfs on a normal system, and the scope of changes and targets for the rescue procedures to apply during an actual failure.
Identify the Boot Stage and Separate SSH Failures
The Unified Extensible Firmware Interface (UEFI) is firmware that initializes the hardware and finds the boot program. The GNU GRand Unified Bootloader (GRUB) is a bootloader that reads and executes the kernel and the initial RAM filesystem, initramfs. The initial user space of initramfs helps find the root device and switch to the actual root. After that, systemd configures services and the login environment.
| State visible on the console | Initial investigations | Tasks not to do immediately |
|---|---|---|
| Cannot find the boot device | Disk connections, firmware boot order, EFI system partition | Do not reinitialize the root filesystem. |
| GRUB menu or command line | Boot file paths, configuration and device identity | Do not unconditionally apply BIOS commands to UEFI. |
| Kernel messages or initramfs shell | Selected kernel, root UUID, storage modules and encryption/LVM | Do not assume the kernel of the running environment as the recovery target version. |
| Emergency mode or service failure | fstab, mounts, affected unit and journal | Do not treat reinstalling GRUB as a universal repair. |
| There is a login screen, but SSH fails. | Address, path, firewall, sshd, authentication | Do not infer kernel boot failure from SSH failure. |
Record the text on the error screen, the selected kernel, and the actions and times just before the change. For VMs like VirtualBox, check whether you can directly access the console of the VM. In this test VM, the console login prompt and normal SSH were confirmed, so operations were not performed in a state that caused the system to be unbootable.
Check the Running Kernel and Actual Boot Mounts
While the system is normally bootable, leave the following information as a separate record. uname -r is the currently running kernel, not a list of all installed kernels. The ii in the dpkg-query output indicates an installed state, and entries like un are not counted as installed kernels.
uname -r
dpkg-query -W -f='${binary:Package} ${db:Status-Abbrev} ${Version}\n' 'linux-image*'
ls -l /boot/vmlinuz-* /boot/initrd.img-*
ls /usr/lib/modules
test -d /sys/firmware/efi && echo 'Booted with UEFI'
findmnt --target / -o TARGET,SOURCE,FSTYPE,OPTIONS
findmnt --target /boot -o TARGET,SOURCE,FSTYPE,OPTIONS
findmnt --mountpoint /boot/efi -o TARGET,SOURCE,FSTYPE,OPTIONS
df -hT /boot /boot/efi /var/tmp
readlink -f /vmlinuz /initrd.img
On a BIOS boot, the EFI-directory test can return nonzero and a dedicated EFI mount may not exist. Interpret these as layout observations, not proof of boot failure. A UUID is a persistent filesystem identifier; verify it against the actual devices rather than copying names from this lab.
The test VM was UEFI, GRUB 2.12, kernel 6.12.107+deb13-amd64, initramfs-tools 0.148.4. /boot was included in the root ext4, not a separate partition, and only /boot/efi was a separate vfat. Even if /boot is the same, servers may have different separate partitions, LVM, or encryption, so device names are not copied for use.
The GRUB menu allows syntax checking and item verification on a normal system as follows. Syntax success does not guarantee firmware booting, disk reading, or kernel execution.
sudo grub-script-check /boot/grub/grub.cfg
sudo grep -E "^(menuentry|submenu)|^[[:space:]]+menuentry " /boot/grub/grub.cfg
The grub-script-check manual describes configuration syntax checking. grub.cfg is generated output; for permanent changes, inspect the source configuration and generation process instead of editing that output directly.
Prepare Console Access and Check for an Older Kernel
If a problem occurs after the new kernel and the previous kernel is actually installed, you can review how to boot into the previous version by opening 'Advanced options for Debian GNU/Linux' in the GRUB console. Depending on VM firmware and settings, the menu entry key and display time may differ, so verify the access method in a normal state.
The verification VM had only one actually installed kernel, and both the standard and recovery items in GRUB were the same version 6.12.107. The recovery mode entry is not the previous kernel. If there is no other version, it does not indicate that selecting the previous kernel will resolve the issue.
If you booted into the previous kernel, check uname -r, services, network, and data, and preserve the problematic kernel and logs. Do not remove the normal kernel first. If it is impossible to boot into any kernel, prepare for console access and rescue from the installation ISO and perform backups. Here, we proceed with the following separate image practice without replacing any normal boot files.
Preserve boot files and create a separate initramfs
mkinitramfs creates an initial filesystem image for the specified kernel. This exercise saves the results to a root-only backup path without overwriting /boot. /var/tmp can be used as the default temporary workspace, so check for available space and permission to execute. Conditions for temporary paths of actual tools can be found in the mkinitramfs documentation.
The following full block is executed from a terminal of a normal Debian system with sudo privileges. Execution stops if a path with the same name exists, and existing records are not overwritten.
sudo bash <<'ROOT'
set -euo pipefail
dest=/var/backups/lf-debian13-32
if test -e "$dest"; then echo "Destination already exists." >&2; exit 1; fi
install -d -m 700 "$dest"
kernel=$(uname -r)
test -f "/boot/vmlinuz-$kernel"
test -f "/boot/initrd.img-$kernel"
test -d "/usr/lib/modules/$kernel"
sha256sum "/boot/vmlinuz-$kernel" "/boot/initrd.img-$kernel" /boot/grub/grub.cfg > "$dest/boot-before.sha256"
cp -a /etc/fstab /etc/default/grub /etc/initramfs-tools/initramfs.conf "$dest/"
mkinitramfs -o "$dest/initrd-lab.img" "$kernel"
lsinitramfs "$dest/initrd-lab.img" > "$dest/initrd-lab-files.txt"
grep -Fx init "$dest/initrd-lab-files.txt"
grep -F "usr/lib/modules/$kernel/" "$dest/initrd-lab-files.txt" > "$dest/kernel-module-files.txt"
test -s "$dest/kernel-module-files.txt"
stat -c 'image bytes=%s' "$dest/initrd-lab.img"
sha256sum -c "$dest/boot-before.sha256"
ROOT
The execution results confirmed the init entry and corresponding kernel module path, and the separate image size was 38,975,420 bytes. Size may vary depending on creation conditions and packages. The original vmlinuz, initrd.img, and grub.cfg hashes were all OK. Creating a separate image and verifying the list is distinguished from actually booting with that image.
The roles and supported scope of the listing tool are detailed in the lsinitramfs documentation. Additional verification is needed on the actual system configuration to ensure that the desired storage device driver, root UUID, and LVM/encryption settings are correct. Simply having a large number of files does not determine whether the image is recoverable.
Check the rescue environment and target root during an actual failure
This section is a recovery procedure that determines the applicable conditions when an actual boot failure is confirmed. On the above VM, the normal boot files were not changed, nor was the actual file replacement performed in rescue. As described in the Debian installation manual's rescue section , enter the rescue item of the installation media or use rescue/enable=true to select the root to recover.
- Secure the server console and backup/restore means, and boot with installation media that matches the existing disk and EFI boot method.
- Select Rescue mode, go through language and hardware checks, and select the actual installed root file system. Do not proceed to the partition initialization stage of a new installation.
- Check whether it is a shell inside the selected root or the installer’s own shell. If it is a shell inside the selected root, you are already working in that environment, so do not chroot to /target again.
- In the installer shell, the selected root may be mounted at /target. Compare the OS and fstab in that directory with the actual devices, and if there is a separate /boot or EFI, connect them correctly, then work in the target environment.
The following commands are executed in the installer environment’s root shell to verify the target. Since it is the root shell, do not use the sudo prefix. This only makes sense when /target is the actual selected root.
lsblk -f
findmnt -R /target
cat /target/etc/os-release
cat /target/etc/fstab
ls /target/usr/lib/modules
ls -l /target/boot
Encryption, RAID, and LVM must first be able to use the corresponding storage layers. Do not apply this simple ext4 and UEFI example unchanged to those storage layouts. If the root itself cannot be read due to corruption, first determine the conditions for file system check and backup restoration, and do not apply e2fsck to a mounted root.
If a manual chroot is required in the installer shell, /target must be the correct root and capable of executing the target shell. If there is a separate /boot, first mount it to the target /target/boot, and the EFI system partition should be mounted to /target/boot/efi using the actual UUID. Do not duplicate already connected items and verify using the findmnt results.
The following block binds the runtime filesystems after you have identified and mounted the correct boot partitions. Stop on any failed mount command and inspect findmnt -R /target before continuing. Recursive slave propagation prevents unmount operations under the target from propagating back to the rescue environment. A chroot changes the apparent filesystem root; it does not boot the installed kernel or establish a security boundary.
Below is an example of connecting runtime mounts and entering the target environment. This command does not replace disk identification. If mounts like /target/dev are already prepared, it is recommended to first use the target shell provided by the installer.
for p in dev proc sys run; do
mount --rbind "/$p" "/target/$p"
mount --make-rslave "/target/$p"
done
chroot /target /bin/bash
Specify the Installed Target Kernel Before Repair
Even inside chroot, uname -r shows the kernel running from the rescue media. Compare the target's installed kernel list, module directory, and vmlinuz file to specify the version. The following is a check executed from the root shell of the target root.
cat /etc/os-release
ls /usr/lib/modules
dpkg-query -W -f='${binary:Package} ${db:Status-Abbrev} ${Version}\n' 'linux-image*'
findmnt --target /boot
findmnt --target /boot/efi
df -hT /boot /boot/efi /var/tmp
read -r -p "Installed kernel version to repair: " target_kernel
test -d "/usr/lib/modules/$target_kernel"
test -f "/boot/vmlinuz-$target_kernel"
Also check the installed generation tools. The next procedure for an environment like this VM using initramfs-tools is not applied as-is to a dracut environment. Before recovery, store the necessary targets such as boot files, configuration, and EFI contents in a separate, access-restricted location. Assign a new name to the backup and do not overwrite the existing good copy.
Only update the actual initramfs after correcting the above causes and confirming storage space, root/boot mounts, target version, and backups. In the following root shell block, select -u if there is an existing image for the target kernel, or -c if there is not. This operation actually modifies /boot.
set -e
test -n "$target_kernel"
test -d "/usr/lib/modules/$target_kernel"
test -f "/boot/vmlinuz-$target_kernel"
repair_record=$(mktemp -d /var/backups/lf-boot-repair.XXXXXX)
for path in "/boot/vmlinuz-$target_kernel" "/boot/initrd.img-$target_kernel" /boot/grub/grub.cfg /etc/fstab /etc/default/grub; do
if test -f "$path"; then cp -a -- "$path" "$repair_record/"; fi
done
printf 'backup: %s\n' "$repair_record"
if test -f "/boot/initrd.img-$target_kernel"; then
update-initramfs -u -k "$target_kernel"
else
update-initramfs -c -k "$target_kernel"
fi
listing=$(mktemp /var/tmp/lf-repair-initrd.XXXXXX)
lsinitramfs "/boot/initrd.img-$target_kernel" > "$listing"
grep -Fx init "$listing"
rm -- "$listing"
update-grub
grub-script-check /boot/grub/grub.cfg
The update-initramfs manual distinguishes updating an existing image from creating a new one. The update-grub manual describes generating GRUB configuration, a different operation from reinstalling the bootloader or repairing firmware boot entries.
If the problem is with the EFI files or firmware registration itself, a separate recovery process is needed to check the target architecture, UEFI/BIOS, Secure Boot, EFI mount, and installed grub/shim packages. Do not automatically add bootloader reinstallation when GRUB can read the kernel, and do not copy BIOS example disk commands to UEFI.
Verify Recovery and Retain the Separate Lab Image
In actual recovery, exit chroot, unmount the subordinate mounts you connected in reverse order, detach the installation media, and then boot from the disk. When unmounting, do not use broad commands that include other operating mounts; check the actual hierarchy with findmnt -R /target. In case of boot failure, preserve the console messages, selected versions, and change history, and respond using the prepared backup and restore procedures.
If the system boots, check uname -r, root and boot mounts, systemctl --failed along with necessary services, new SSH connections, actual responses, and data. Distinguish between the fact that the login screen appeared and the fact that the originally provided functions have been restored.
uname -r
findmnt --target /
findmnt --target /boot
findmnt --mountpoint /boot/efi
sudo systemctl --failed --no-pager
systemctl is-active ssh
ip -brief address
ip route
Separate image exercises performed in a normal state did not change the original /boot, so restoring boot files is not necessary. Separate images and copies of lists, hashes, and configurations have been preserved in /var/backups/lf-debian13-32. When deleting only unnecessary exercise images, ensure you do not confuse the original /boot/initrd.img and its path, and first decide whether to retain the recovery records.




