Knowledge Base:Recovering from a kernel boot failure

Synopsis

Booting a Gentoo Linux system fails to boot up properly. No recovery mode is presented (such as a single-user login) but the boot loader does work properly.

Environment

Any Gentoo Linux installation.

Analysis

Boot failures can have several reasons. This article will focus on generic approaches to recover from such failures.

The approaches are two-fold:

1. Try to get a root prompt from the (malfunctioning) system, or
2. Boot from a LiveCD or other environment, mount the system and chroot to perform recovery steps.

Resolution

There are several possible resolutions to fix a boot failure. The first one, which covers how to get a root prompt, is especially useful if partitions are reachable. The second one works in almost all circumstances as it is based on the installation of Gentoo.

Getting a root prompt

To get a root prompt, reboot the system until the Linux boot loader (such as GRUB) appears. In the boot loader, edit the boot entry. For instance, with GRUB, this is done by pressing the E key (for edit). On the kernel line, add init=/bin/sh:

kernel /kernel root=/dev/sda3 init=/bin/sh

If the boot failure is because of a wrong root= setting, then correct it using the kernel line as well. When finished editing, boot the entry (for GRUB, this means pressing the B key (for boot).

These changes (which are not persistent) will boot the system, but instead of calling the init binary, it immediately drops the init process into a root shell. From this shell recovery steps can be performed. If persistent changes need to be made the root file system, as well as all other partitions that needs changes, should be mounted as read-write:

root #mount -o remount,rw /

root #mount -a

Booting back from a LiveCD or other environment

Boot from the LiveCD (or a different environment) until the environment grants shell access. Create the /mnt/gentoo mount point (if one does not exist) and mount the root file system on it:

root #mkdir /mnt/gentoo

root #mount /dev/sda3 /mnt/gentoo

Next, bindmount /proc, /dev and /sys and /run on top the /mnt/gentoo mountpoint:

root # mount --types proc /proc /mnt/gentoo/proc

root # mount --rbind /sys /mnt/gentoo/sys

root # mount --rbind /dev /mnt/gentoo/dev

root # mount --bind /run /mnt/gentoo/run

Note
These --make-rslave operations are needed for systemd support later in the installation.

root # mount --make-rslave /mnt/gentoo/sys

root # mount --make-rslave /mnt/gentoo/dev

root # mount --make-slave /mnt/gentoo/run

Finally, chroot into the environment, mount the remaining partitions, and start recovering the system:

root #chroot /mnt/gentoo /bin/sh

root #source /etc/profile

root #mount -a

Once finished with the recovery steps, umount all partitions, exit the chroot, umount the remaining partitions, and reboot back into the system to see if the recovery has succeeded:

root #umount -a

root #exit

root #umount -l /mnt/gentoo/{dev,proc,sys,run,}

root #sync

root #reboot

See also

• Project:Portage/Fixing broken portage — provides guidance on how to manually update or fix a broken Portage installation - particularly in the event emerge -v1 sys-apps/portage cannot be run.
• Fix my Gentoo — rescuing an installation when a chroot is not possible
• Support — provide support for technical issues encountered when installing or using Gentoo Linux
• Troubleshooting — provide users with a set of techniques and tools to troubleshoot and fix problems with their Gentoo setups.