Custom Initramfs

initramfs is a root filesystem which is embedded into the kernel and loaded at an early stage of the boot process. It is the successor of initrd. It provides early userspace which lets you do things that the kernel can't easily do by itself during the boot process.

Using initramfs is optional. By default, the kernel initializes hardware using built-in drivers, mounts the specified root partition, loads the init system of the installed Linux distribution. The init system then loads additional modules and starts services until it finally allows you to log in. This is a good default behaviour and sufficient for many users. initramfs is for users with advanced requirements, for users who need to do things as early as possible, before the root partition is mounted.

Here are some examples of what you can do with initramfs:


 * Customize the boot process (e.g. print a welcome message, boot splash, ...)
 * Load modules (e.g. a third party driver that can not be integrated into the kernel directly)
 * Mount the root partition (for encrypted, logical, and otherwise special partitions)
 * Provide a minimalistic rescue shell (if something goes wrong)
 * Anything the kernel can't do (as long as you can do it in user space, e.g. by executing commands)

If you don't have advanced requirements, you do not need initramfs.

Prerequisites
There are countless ways to make an initramfs. You can choose not to create an initramfs at all but let other apps, such as Genkernel or Dracut, do the work for you. If you are lucky, one of them does what you want out of the box, and you don't need to bother with how initramfs works and what it does anymore. If you're unlucky, they don't do what you want and you have to extend their functionality, or even build an initramfs all by yourself.

The initramfs usually contains at least one file,. This file is executed by the kernel as the main init process (PID 1). It has to do all the work. In addition, there can be any number of additional files and directories that are required by. They are usually files you will also find on any other root filesystem, such as for device nodes,  for kernel information,  for binaries, and so on. The structure of the initramfs can be simple, or it can be complicated, depending on what you are planning to do.

When the kernel mounts the initramfs, your target root partition is not yet mounted, so you can't access any of your files. That means there is nothing but the initramfs. So everything you need, everything you want, you have to include it in your initramfs. If you want a shell, you have to include it in your initramfs. If you want to mount something, you need a mount utility. If you need to load a module, your initramfs has to provide both the module, as well as a utility to load it. If the utility depends on libraries in order to work, you have to include the libraries as well. This seems complicated, and it is, because the initramfs has to function independently.

Basics
In this section you will learn the easy and straightforward way to initramfs creation. You will make a functional - albeit minimalistic - initramfs which you then can extend according to your own requirements.

Directory Structure
Create the directory that will later become your initramfs root. For consistency. we'll work in, but any directory would do. Create the initramfs root directory and cd into it.

Create a basic directory layout.

Device Nodes
Most things you do in initramfs will require a couple of device nodes to be present, especially the device for your root partition. Throughout this document, will be used as example device. Copy basic device nodes.

Which devices you need exactly depends entirely on what you are going to use initramfs for. Please adapt to your own needs.

Applications
Any binary you want to execute at boot needs to be copied into your initramfs layout. You also need to copy any libraries that your binaries require. To see what libraries any particular binary requires, use the tool ldd. An example examining what libraries requires:

Here you see that for to work in your initramfs, you not only need to copy  to your, but also  and  to your. Note that you don't need the.

Additionally, some applications may be depend on other files and libraries to work. For example, also needs a terminfo file  from, so that has to be copied to your initramfs as well. To find these dependencies, tools like equery and strace prove to be helpful.

Busybox
Instead of collecting countless utilities and libraries (and never seeing the end of it), you can just use. It's a set of utilities for rescue and embedded systems, it contains a shell, utilities like ls, mkdir, cp, mount, insmod, and many more - all in a single binary called. For busybox to work properly in a initramfs, you'll firstly need to emerge it with the static USE flag enabled, then copy the binary into your initramfs layout as :

Init
The file structure of your initramfs is almost complete. The only thing that is missing is, the executable in the root of the initramfs that is executed by the kernel once it is loaded. Because includes a fully functional shell, this means you can write your  binary as a simple shell script (instead of making it a complicated application written in Assembler or C that you have to compile).

The following example realizes this executable as a minimalistic shell script, based on the busybox shell:

This example needs some device nodes to work, mainly the root block device. Change the script and copy the the corresponding node to fit your needs.

Lastly, make the executable:

Packaging Your Initramfs
Your initramfs now has to be made available to your kernel at boot time. This is done by packaging it as a compressed cpio archive. This archive is then either embedded directly into your kernel image, or stored as a separate file which can be loaded by grub during the boot process. Both methods perform equally well, simply choose the method that you find most convenient.

Kernel Configuration
With either method, you need to enable support for Initial RAM filesystem and RAM disk (initramfs/initrd) support for the initramfs functionality.

Embedding into the Kernel
If you want the initramfs to be embedded into the kernel image, edit your kernel config and set Initramfs source file(s) to the root of your initramfs, (e.g ):

Now when you compile your kernel it will automatically put the files into a cpio archive and embed it into the kernel image. You will need to rebuild your kernel any time you make any changes to your initramfs.

Creating a Separate File
You can create a standalone archive file by running the following commands:

This will create a file called in your  directory. You now need to instruct grub to load this file at boot time, you do this with the initrd line.

Finalizing
You can now reboot your machine. On boot, the kernel will extract the files from your initramfs archive automatically and execute your script, which in turn should then take care of mounting your root partition and exec the init of your installed Linux distribution.

Functionality
Now that you've covered the initramfs basics, in this section you will learn how to extend your script with more advanced functionality.

Rescue Shell
If you want to be dropped to a rescue shell if an error occurs, you can add the following function to your and call it when something goes wrong.

In the example below, the rescue_shell will be executed if the root partition fails to mount: