Wiki

• FrontPage
• RecentChanges
• FindPage
• HelpContents
• initramfs

Translation(s): none

What is an initramfs

The initramfs is a temporary filesystem image used to help the Linux Kernel mount the root filesystem and run the main Init system.

The kernel has 3 ways to find and mount the root filesystem:

1. all required device and filesystem drivers can be compiled into the kernel, The kernel uses the root= kernel command line option and if present, the init= option is used to find the system's main Init system.

2. some device and filesystem drivers can be built as modules and stored in an Initrd. The initrd must contain a binary /linuxrc which loads the driver modules. It is also possible to mount the final root filesystem via linuxrc and use the pivot_root syscall.

3. An initramfs can be used to run tasks from userspace. The work previously done by the kernel is instead done by an /init stored in the initramfs. This binary is responsible for doing all the things the kernel would have done. The initramfs must be a cpio archive.

See https://www.kernel.org/doc/html/latest/filesystems/ramfs-rootfs-initramfs.html for more information.

By default, Debian uses an initramfs created and managed by the initramfs-tools package.

Why use initramfs

Using an initramfs allows:

• the kernel to be smaller. Much of the kernel initialization and bootstrap code can be moved into the initramfs and run in user mode rather than being part of the kernel. This includes tasks like finding the real root filesystem, boot-time networking setup, handling of initrd-style ramdisks, power management setup. This does not free memory for the running system, since the Linux kernel already dumps initialization code when it is no longer needed.
• easier customization of the early boot process. An initramfs allows the user to change how the system boots with userspace code rather than needing to patch the kernel. Userspace code is easier to write - a full C library with memory protection, etc can be used.
• the kernel to be better written. Because userspace code interacts with the kernel via system calls, supporting an initramfs required the kernel initialization code to be less "magic" (cleaner, safer code).

Configuring the initramfs with initramfs-tools

The initramfs-tools package is configured through the files in /etc/initramfs-tools/. You can edit /etc/initramfs-tools/initramfs.conf but it is better to putting files into /etc/initramfs-tools/conf.d/. See the man-page initramfs.conf(5) for details.

For example, you can change modules to be included in the initramfs by the driver policy by setting MODULES=dep in a file named /etc/initramfs-tools/conf.d/driver-policy: this will cause the system to include only the drivers the system thinks it needs, instead of most available modules: beware that if a needed driver isn't included in the initramfs your system will fail to boot.

If you wish to add an executable file or libraries to an initramfs image, you need to write an initramfs hook and place it under the directory /etc/initramfs-tools/hooks/, take a look at initramfs-tools(7) man-page for a comprehensive tutorial. Since these hooks are POSIX shell script, don't forget to make it executable.

Features available in an initramfs

The initramfs includes:

• A small C library (klibc) to support initramfs applications.

• A small kinit application created with klibc.

How to inspect initramfs

The initramfs-tools-core package provides lsinitramfs to list files inside the initramfs and unmkinitramfs to extract files from the initramfs.

Alternatively, you can do the following (assuming path/to/initrd already exists as empty working directory):

• If the output of file -L /initrd.img is ASCII cpio archive (SVR4 with no CRC), consider the initrd image to have microcode prepended.

  • extract the microcode by cd path/to/initrd/; cpio -i </initrd.img and read the STDERR display (in my case 48).

  • extract the basic initrd by cd path/to/initrad/; dd if=/initrd.img of=initrd.img bs=512 skip=48; zcat initrd.img |cpio -i (adjust skip values matching the cpio STDERR output).

• Otherwise, extract the initrd directly by cd path/to/initrad/; zcat /initrd.img |cpio -i

The microcode cpio archive size can be independently checked by cpio -t </initrd.img >/dev/null

(This manual method somehow worked for me at one point. But this is not reliable. /usr/bin/lsinitramfs has a comment "cpio won't tell us the true size".)

Please note Debian currently use gzip as the compression method and the above method assumes so. Ubuntu seems to start using LZ4 as of March 2018. initramfs-tools in Debian supports LZ4 since Debian buster (893845).

Using CPU microcode data

This basic initramfs image may be prepended with an uncompressed cpio archive holding microcode data to be loaded very early in the boot process.

At boot time, the kernel performs the followings:

• If an uncompressed cpio archive exists at the start of the initramfs, extract and load the microcode it contains into the CPU. Use the rest of initramfs file as the basic initramfs. Otherwise, use the whole initramfs file as the basic initramfs.
• unpack the basic initramfs by treating it as compressed (gzip by default on Debian, LZ4 on Ubuntu) cpio archive into a RAM-based file system.
• mount and use the RAM-based filesystem as the initial root filesystem.

See also

See:

• RescueInitramfs

• InitramfsDebug

• initramfs-tools

• The initramfs chapter in the Debian Kernel Handbook

• Ramfs, rootfs and initramfs section of the Linux kernel documentation

• ramfs

• rootfs

CategoryKernel | CategoryBootProcess