Translation(s): none

initramfs-tools is used in Debian to build the initramfs that contains the early userspace and the needed kernel modules to be able to mount any possible root.


To fix wrong fs recognition work around boot with


In releases older than Debian 8 (jessie), it may be necessary to add a delay for disks to be discovered before setting up RAID and LVM. Boot with e.g.


Rescue shell (also known as initramfs shell)

Read man initramfs-tools to learn about the break=something kernel parameter (where valid arguments for something are: top, modules, premount, mount, mountroot, bottom, init), which starts a debug shell. You can try, for example, break=premount. You can edit /boot/grub/grub.cfg to add this to the end of the kernel line, or you can do it interactively from the grub boot menu: "e" to edit, and "b" to boot once you've edited the kernel line.

Ok, now you landed in the initramfs debug shell. This is a surprisingly complete environment provided by "busybox". You can use vi, for example, but not everything is fully the same as bash. For example, sleep only accepts integer arguments. You may find more complete commands in /bin (for example, /bin/sleep does accept decimal arguments, but you will need to use /bin/sleep in your scripts).

The following steps should help to narrow down the problem.

You can exit the shell with exit or ^D and the boot should resume.

initramfs content

It can happen that due to a bug in the initramfs creation a newer initramfs lacks important libraries or utilities. Easiest way is to check contents with lsinitramfs

Old way is to compare the file list of working contra non-working initramfs.

Notice that both methods don't work with multi-segmented initramfs images, which may consist of an uncompressed cpio archive with a compressed one, concatenated together. The getinitramfs script proposed in the bug report #790095 to initramfs-tools may help you to unpack such initrd images.

Saving debug information

If you specify debug as a kernel option during boot, initramfs-tools (>= 0.92m) writes shell script traces to /run/initramfs/initramfs.debug, or (if /run is unavailable in the initramfs) /run/initramfs/initramfs.debug, which will be available after the system has booted.

You can write other data to files in that directory to be able to access them later, when the system has booted. Since /dev is a tmpfs however, they won't persist across a reboot.

If you need to get debug data off the system and it can mount the root filesystem, you can do something like

mount -o remount,rw /root
dmesg > /root/root/initramfs.dmesg
mount -o remount,ro /root

If that does not work, use a USB stick: plug it in, observe the kernel output, mkdir /mnt, mount the device node there, and write to the flash drive. Remember to umount before pulling out the stick.

See also

Managing the initial ramfs (initramfs) archive

CategoryKernel | CategoryBootProcess