Custom Initramfs

initramfs is a root filesystem that 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 can do things 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 eventually allows you to log in. This is a good default behavior and sufficient for many users. initramfs is for users with advanced requirements; for users who need to do things as early as possible, even before the root partition is mounted.

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

Mount the root partition (for encrypted, logical, and otherwise special partitions);
Provide a minimalistic rescue shell (if something goes wrong);
Customize the boot process (e.g. print a welcome message, boot splash, etc.);
Load modules (e.g. third party drivers);
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 don't need initramfs.

Prerequisites

There are countless ways to make an initramfs. You can choose not to create an initramfs at all but let tools, 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.

An initramfs contains at least one file called /init. 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 /init. They are usually files you'll also find on any other root filesystem, such as /dev for device nodes, /proc for kernel information, /bin for binaries, and so on. The structure of an 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 a basic initramfs directory structure that will later become your initramfs root. For consistency, we'll work in /usr/src/initramfs, but any location would do. If you choose another location, please adapt accordingly.

root #mkdir -p /usr/src/initramfs/{bin,dev,etc,lib,lib64,mnt/root,proc,root,sbin,sys}

Device nodes

Most things the initramfs does will require a couple of device nodes to be present, especially the device for the root partition. Throughout this document, /dev/sda1 will be used as example device. Copy basic device nodes from the root filesystem to the initramfs example location:

root #cp -a /dev/{null,console,tty,sda1} /usr/src/initramfs/dev/

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

Note
More advanced approaches to device nodes are covered in the Dynamic devices section.

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 ldd tool. For example, the dev-util/strace binary requires:

user $ldd /usr/bin/strace

    linux-vdso.so.1 (0x00007fff271ff000)
    libc.so.6 => /lib64/libc.so.6 (0x00007f5b954fe000)
    /lib64/ld-linux-x86-64.so.2 (0x00007f5b958a9000)

Here you see that for /usr/bin/strace to work in your initramfs, you not only need to copy /usr/bin/strace to your /usr/src/initramfs/bin, but also /lib64/libc.so.6 and /lib64/ld-linux-x86-64.so.2 to your /usr/src/initramfs/lib64. The exception is linux-vdso.so.1 which is provided by the kernel.

Some applications might depend on other files and libraries to work. For example, app-editor/nano needs a terminfo file /usr/share/terminfo/l/linux from sys-libs/ncurses, so you have to copy it to your initramfs as well. To find these dependencies, tools like equery and strace prove to be most helpful.

Busybox

Instead of collecting countless utilities and libraries (and never seeing the end of it), you can just use sys-apps/busybox. 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 /bin/busybox. For busybox to work properly in a initramfs, you need to emerge it with the static USE flag enabled, then copy the /bin/busybox binary into your initramfs layout as /usr/src/initramfs/bin/busybox:

root #

USE="static" emerge -av busybox

root #cp -a /bin/busybox /usr/src/initramfs/bin/busybox

Note
Use ldd to verify that the binary is static.

Init

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

The following example shows a minimalistic shell script, based on the busybox shell:

FILE /usr/src/initramfs/initminimalistic /init example

#!/bin/busybox sh

# Mount the /proc and /sys filesystems.
mount -t proc none /proc
mount -t sysfs none /sys

# Do your stuff here.
echo "This script just mounts and boots the rootfs, nothing else!"

# Mount the root filesystem.
mount -o ro /dev/sda1 /mnt/root

# Clean up.
umount /proc
umount /sys

# Boot the real thing.
exec switch_root /mnt/root /sbin/init

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

Don't forget to make the /init file executable:

root #chmod +x /usr/src/initramfs/init

Packaging

Your initramfs now has to be made available to the kernel at boot time. This is done by packaging it as a compressed cpio archive. This archive is then either embedded directly into the 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 you prefer.

Kernel configuration

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

KERNEL CONFIG_BLK_DEV_INITRD=y

General setup  --->
    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support

Also enable all drivers, filesystems, and other settings that are required for booting and accessing your root partition. If you select such drivers as modules, you'll have to collect and integrate the module files into your initramfs and load them in your /init. Generally this means a lot of unnecessary extra work, so just use built-in drivers for now.

Embedding into the Kernel

If you want the initramfs to be embedded into the kernel image, set Initramfs source file(s) to the root of your initramfs, (e.g. /usr/src/initramfs):

KERNEL CONFIG_INITRAMFS_SOURCE="/usr/src/initramfs"

General setup  --->
    (/usr/src/initramfs) Initramfs source file(s)

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:

root #

cd /usr/src/initramfs

root #find . -print0 | cpio --null -ov --format=newc | gzip -9 > /boot/custom-initramfs.cpio.gz

This will create a file called custom-initramfs.cpio.gz in your /boot directory. You now need to instruct your bootloader to load this file along with the kernel, in case of GRUB you do this with the initrd line:

FILE /boot/grub/grub.cfgGRUB2 initrd example

linux 3.12.6-gentoo
initrd custom-initramfs.cpio.gz

Note
If you are unfamiliar with bootloader configuration, please refer to GRUB2 or GRUB.

External file list

An external file list, or cpio list, describes files to be included into the initramfs. This file list is processed by an utility that comes with the Linux kernel, usr/gen_init_cpio. It can be used for both embedded and standalone initramfs, either by using it as INITRAMFS_SOURCE directly or by running the utility from a shell. This lets you build the initramfs dynamically, always using the latest files from your system, but compared to populating a real directory /usr/src/initramfs, it's less intuitive and requires more knowledge in regards to device nodes and such.

root #/usr/src/linux/usr/gen_init_cpio initramfs.list > initramfs.cpio

FILE initramfs.listcpio list example

# Custom Initramfs minimal example
dir /dev 0755 0 0
file /init /usr/src/initramfs/init 0755 0 0

Note
This method is for advanced users. Run gen_init_cpio without arguments for cpio list syntax and a more detailed example.

Finalizing

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

Functionality

Now that you've covered the initramfs basics, in this section you will learn how to extend your /init 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 /init and call it when something goes wrong.

FILE /usr/src/initramfs/initRescue shell functionality

rescue_shell() {
    echo "Something went wrong. Dropping to a shell."
    exec sh
}

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

FILE /usr/src/initramfs/initInvoking the rescue shell

mount -o ro /dev/sda1 /mnt/root || rescue_shell

Dynamic devices

For populating /dev dynamically, you can use either devtmpfs or mdev. Please note that the kernel can take some time detecting devices (such as external USB drives), so you may also have to add a sleep statement to your script.

devtmpfs

Provided by the kernel, devtmpfs is designed to offer device nodes during early boot.

KERNEL CONFIG_DEVTMPFS=y

Device Drivers  --->
    Generic Driver Options  --->
        [*] Maintain a devtmpfs filesystem to mount at /dev

You can include the following snippet in your /init script to have it mount at boot:

FILE /usr/src/initramfs/initmount devtmpfs

mount -t devtmpfs none /dev

Don't forget to unmount it again in the cleanup phase of the script:

FILE /usr/src/initramfs/initumount devtmpfs

umount /dev

mdev

Although devtmpfs is the preferred solution today, you can alternatively use mdev, the udev replacement of busybox.

KERNEL CONFIG_UEVENT_HELPER=y

Device Drivers  --->
    Generic Driver Options  --->
        [*] Support for uevent helper

For mdev to work, you have to make /sbin/mdev a symlink to /bin/busybox in your initramfs.

root #ln -s ../bin/busybox /usr/src/initramfs/sbin/mdev

Then add the following snippet to your /init, after mounting /proc and /sys:

FILE /usr/src/initramfs/initAdding mdev support to /init

echo /sbin/mdev > /proc/sys/kernel/hotplug
mdev -s

Mount by UUID or label

With Dynamic devices enabled, you might prefer to use UUID or label to mount the root partition instead of using a static device name. For that purpose, busybox comes with a utility called findfs.

FILE /usr/src/initramfs/initmount using findfs

mount -o ro $(findfs UUID=845b2454-42a3-19ef-6ec5-238a358c365b) /mnt/root
# or
mount -o ro $(findfs LABEL=myroot) /mnt/root

Doing it this way is simple, but it means that your UUID or label is hardcoded in the /init. Alternatively, you can also use Kernel parameters.

Kernel parameters

If you want to use kernel parameters instead of hardcoding device names or UUIDs, you will have to parse /proc/cmdline. There are many ways to do so, the following method is just an example to give you the general idea. It uses string manipulation of the shell and only supports key=value parameters. Add the following function to your /init and call it whenever you need a kernel parameter.

FILE /usr/src/initramfs/initAdding a simple cmdline parser function

cmdline() {
    local value
    value=" $(cat /proc/cmdline) "
    value="${value##* $1=}"
    value="${value%% *}"
    [ "$value" != "" ] && echo "$value"
}

The function is called with the name of the kernel parameter you are interested in. In the example below, it uses the root parameter to mount the root partition.

FILE /usr/src/initramfs/initMount rootfs by cmdline

mount -o ro $(findfs $(cmdline root)) /mnt/root

It works for both root=/dev/sda1 and root=UUID=845b2454 but will fail when the parameter is missing.

LVM

If your root partition is located on a logical volume, you need to include the LVM binary in your initramfs. You can get a static binary by enabling the static USE flag for sys-fs/lvm2. Copy it to your initramfs /sbin directory.

Note
The static LVM binary may also be called /sbin/lvm.static. Use ldd to verify that the binary is static.

root #cp -a /sbin/lvm /usr/src/initramfs/sbin/lvm

Now you can enable your LVM root partition in /init. This example assumes that your volume group is called VG, and your root volume is called root. Replace them with the names you chose when creating the volume.

FILE /usr/src/initramfs/initSetting up the root volume

lvm vgscan --mknodes # creates /dev/mapper/control
lvm lvchange -a ly VG/root
lvm vgscan --mknodes # creates /dev/mapper/VG-root and /dev/VG/root

The root partition may then be called /dev/VG/root or /dev/mapper/VG-root.

Note
Calling vgscan is optional, but recommended, just in case device nodes are missing.

Recent versions of sys-fs/lvm2 rely on sys-fs/udev to create the named LV device nodes, but there is no udev in a simple initramfs. The following choices are available:

Use vgscan as shown above (simplest solution)
Mount by UUID or label instead of using /dev/VG/root. It works because findfs is happy with just /dev/dm-42
Build a LVM binary with the -udev USE flag (specifically for the initramfs only!)
Disable udev dependency by including a minimal /etc/lvm/lvm.conf in the initramfs:

FILE /usr/src/initramfs/etc/lvm/lvm.confDisable udev in lvm.conf

activation {
    # Set to 0 to disable udev synchronisation (if compiled into the binaries).
    udev_sync = 0
    # Set to 0 to disable the udev rules installed by LVM2
    udev_rules = 0
}

Software RAID

Normally the Linux kernel will automatically scan for any "Linux raid autodetect" partitions and start as many software RAIDs as it can find. But if you use an initramfs, the kernel will not automatically scan for RAIDs until it is told to. In the following example instructs the kernel to scan for software RAIDs and start as many as it can find. This will actually start all autodetected arrays, not just /dev/md0:

FILE /usr/src/initramfs/initAdding RAID autodetect support to /init

raidautorun /dev/md0

Note
"Linux raid autodetect" won't work for any recent setups, unless you specifically set up with partitions of type "fd" and used 0.90 metadata for your Software RAID.

mdadm

Without "Linux raid autodetect" partitions, or if you need an advanced RAID setup, you have to include mdadm in your initramfs. You can get a static binary by enabling the static USE flag for sys-fs/mdadm.

Copy the binary /sbin/mdadm and your /etc/mdadm.conf into your initramfs:

root #

cp -a /sbin/mdadm /usr/src/initramfs/sbin

root #

cp -a /etc/mdadm.conf /usr/src/initramfs/etc

Note
Use mdadm --detail --scan if you do not yet have a mdadm.conf.

Edit the mdadm.conf in your initramfs to your liking. An example mdadm.conf follows:

FILE /usr/src/initramfs/etc/mdadm.confmdadm.conf example

DEVICE /dev/sd?*
ARRAY /dev/md0 UUID=627125a5:abce6b82:6c738e49:50adadae

This mdadm.conf will scan all /dev/sd?* devices and assemble the RAID device fitting the UUID 627125a5:abce6b82:6c738e49:50adadae.

Note
If your mdadm.conf has additional conditions such as metadata and name, it may be more practical to remove them. The UUID alone should be sufficient.

Now you can initialize your Software RAID in /init:

FILE /usr/src/initramfs/initAssemble software RAIDs with mdadm

mdadm --assemble --scan

With this, you should be able to mount your root partition /dev/md0.

DM-Crypt

If your root partition is LUKS encrypted, you need to include the cryptsetup binary in your initramfs. You can get a static binary by setting the static USE flag for sys-fs/cryptsetup. Copy it to your initramfs /sbin directory. Since cryptsetup also often requires the use of the kernel's random device, include them as well.

Note
If you have problems getting a static cryptsetup binary, try nettle or kernel instead of the default gcrypt USE flag.

root #

cp -a /dev/{urandom,random} /usr/src/initramfs/dev

root #cp -a /sbin/cryptsetup /usr/src/initramfs/sbin/cryptsetup

Now you can unlock your encrypted root partition in /init:

FILE /usr/src/initramfs/initSetting up LUKS encryption in /init

cryptsetup -T 5 luksOpen /dev/sda1 luksroot

Once you entered your passphrase, your root partition will be available as /dev/mapper/luksroot.

Encrypted keyfile

If you need encrypted keyfiles, use cryptsetup to encrypt them. It keeps your initramfs simple as that's the encryption tool you already have - no need to add other binaries. Plus, unlike some of the alternatives, it offers a nice password prompt.

The following example creates a random 512 byte key, encrypted with LUKS, and adds it to your LUKS container /dev/sda1.

Note

Current versions of cryptsetup use 4096 instead of 2056 blocks for LUKS metadata. With the --align-payload=1 parameter, it is back to 2056 blocks.
cryptsetup also offers --keyfile-size and --keyfile-offset options, which can be used for other key sizes or multiple keys in one container.

root #

dd if=/dev/zero of=/usr/src/initramfs/root/key.luks count=2057

root #

cryptsetup --align-payload=1 luksFormat /usr/src/initramfs/root/key.luks

root #

cryptsetup luksOpen /usr/src/initramfs/root/key.luks lukskey

root #

dd if=/dev/urandom of=/dev/mapper/lukskey

root #

cryptsetup luksAddKey /dev/sda1 /dev/mapper/lukskey

Unlocking the root device using this key in your /init can then be done like this:

FILE /usr/src/initramfs/initLUKS encryption with keyfiles

# Obtain the key
cryptsetup -T 5 luksOpen /root/key.luks lukskey

# Unlock the root partition
cryptsetup --key-file /dev/mapper/lukskey luksOpen /dev/sda1 luksroot

# Clean up the key
cryptsetup luksClose lukskey

As before, your root partition should then be available as /dev/mapper/luksroot.

Networking

If you need networking in your initramfs, all required network related drivers have to be built into your kernel, and you'll have to configure the network interfaces in your /init. How exactly this has to be done, depends on your network situation. The following sections cover only the most common cases.

Static IP

If your network situation allows you to use a static network IP, you can set it up using the ifconfig and route commands, both of which are included in Busybox. This is by far the easiest solution, so if it's at all possible, go for it.

FILE /usr/src/initramfs/initStatic network IP setup in /init

ifconfig eth0 10.0.2.15
route add default gw 10.0.2.2

DHCP

To obtain a dynamic IP address from your network's DHCP server, you need a DHCP client. Busybox comes with a minimalistic DHCP client called udhcpc, which is sufficient for most users. Unfortunately, udhcpc has a dependency: it requires the help of a separate script to actually configure the network interface. An example for such a script is included in the Busybox distribution, but it's not installed by Gentoo. You will have to obtain it directly from the Busybox tarball (it's called examples/udhcp/simple.script) or download it from the Busybox project page.

Copy the script to your initramfs and make it executable.

root #

cp simple.script /usr/src/initramfs/bin

root #chmod +x /usr/src/initramfs/bin/simple.script

Edit the script's first line to read #!/bin/busybox sh or create a symlink for /bin/sh:

root #ln -s busybox /usr/src/initramfs/bin/sh

Now, you can obtain a dynamic IP address for eth0 using DHCP:

FILE /usr/src/initramfs/initNetwork setup using DHCP

ifconfig eth0 up
udhcpc -t 5 -q -s /bin/simple.script

DNS

Your network should be up and running now. However, that's only if you know exactly which IPs to talk to. If all you have is a host or domain name, it's a different story entirely. In that case, you need to be able to resolve hostnames. Unfortunately, this is where our luck leaves us. Until now, everything could be done with just the static binary of Busybox - however, this is not the case with DNS.

Note
Additional libraries are required to make DNS work.

This is because sys-libs/glibc itself dynamically includes additional libraries for DNS lookups. As long as you don't need that functionality, you're fine, but if you need it, you have no choice but to include those libraries in your initramfs. The only alternative would be building Busybox against another libc such as sys-libs/uclibc, however that would go beyond the scope of this article.

This is a good chance to demonstrate how to use (dev-util/strace) to reveal hidden dependencies.

user $strace busybox ping wiki.gentoo.org 2>&1 | grep open

open("/etc/nsswitch.conf", O_RDONLY|O_CLOEXEC) = 3
open("/etc/host.conf", O_RDONLY|O_CLOEXEC) = 3
open("/etc/resolv.conf", O_RDONLY|O_CLOEXEC) = 3
open("/etc/ld.so.cache", O_RDONLY|O_CLOEXEC) = 3
open("/lib64/libnss_files.so.2", O_RDONLY|O_CLOEXEC) = 3
open("/lib64/libc.so.6", O_RDONLY|O_CLOEXEC) = 3
open("/lib64/ld-linux-x86-64.so.2", O_RDONLY|O_CLOEXEC) = 3
open("/etc/hosts", O_RDONLY|O_CLOEXEC)  = 3
open("/etc/ld.so.cache", O_RDONLY|O_CLOEXEC) = 3
open("/lib64/libnss_dns.so.2", O_RDONLY|O_CLOEXEC) = 3
open("/lib64/libresolv.so.2", O_RDONLY|O_CLOEXEC) = 3
open("/etc/resolv.conf", O_RDONLY|O_CLOEXEC) = 3

As you can see, the command accesses quite a lot of files, some of which are mandatory for it to work.

Copy the necessary libraries to your initramfs:

root #cp /lib64/libnss_{dns,files}.so.2 /lib64/{libresolv,ld-linux-x86-64}.so.2 /lib64/libc.so.6 /usr/src/initramfs/lib64

Create a /etc/resolv.conf with at least one useable nameserver. Note that this step may be done automatically if you use DHCP.

root #echo nameserver 10.0.2.3 > /usr/src/initramfs/etc/resolv.conf

With this, DNS lookups should now work for you.

Note
If it still does not work, you might be suffering from bug 17250. As a workaround, set LD_LIBRARY_PATH="/lib64" and try again.

Troubleshooting

The following section tries to provide help with common issues and pitfalls you may run into.

Static vs. dynamic binaries

Any custom binaries you need to use in your initramfs before mounting have to be fully functional, independent from any files you may have installed on your root partition. This is much easier to achieve with static binaries (which usually work as single file) than with dynamic binaries (which need any number of additional libraries to work).

Gentoo provides static binaries for some ebuilds. Check if the ebuild for your binary offers a static or -dynamic USE flag. This is by far the easiest method to get a static binary, but unfortunately only a select few ebuilds support it.

Many applications also offer static builds with an option in their configure scripts. There is no standard name for the option, it may be --enable-static or something similar. When compiling a package manually, check the list of available options by using ./configure --help to see if the package supports building static binaries.

You can check whether or not a binary is static by using the ldd command. The strace command is also very useful to find out about additional dependencies. By using equery files it is possible to see which files a certain package has brought into your system, some of which may also be candidates for additional dependencies of that package.

Note

See Applications for a ldd usage example.
See DNS for a strace usage example.

Including libraries into your initramfs in order to make a dynamic executable work is a last resort only. It makes the initramfs much larger than necessary and harder to maintain, as the dependencies might change with every update of the program in question.

lddtree

If you decide to go with dynamic binaries, app-misc/pax-utils comes with a Python script lddtree which will handle the collection of libraries for you:

Note
If the --copy-to-tree option is missing, enable the python useflag.

root #

lddtree --copy-to-tree /usr/src/initramfs /usr/bin/nano

That will copy the binary and all its libraries to your initramfs structure - but not any of the runtime dependencies. For more details refer to lddtree --help.

Kernel panics

When working with initramfs and writing custom init scripts for it, you may experience the following kernel panic on boot:

Kernel panic - not syncing: Attempted to kill init!

This is not an error in the kernel, but an error in your /init script. This script is executed as the init process with PID 1. Unlike other processes, the PID 1 init process is special. It is the only process that is started by the kernel on boot. It's the process that takes care of starting other processes (boot process, init scripts) which in turn start other processes (daemons, login prompts, X), which in turn start other processes (bash, window manager, browser, ...). The init process is the mother of all other processes, and therefore it mustn't be killed. On shutdown, it's again the init process that takes care of cleaning up by shutting down other processes first, then running processes that will unmount the filesystems, until it is safe to actually do a shutdown without corrupting anything.

If you have some error in your /init script, that causes the init process to end, this basically means there are no processes left to run, there is nothing that could take care of cleaning up, and the kernel has no choice but to panic. For this reason there are some things in /init that you can't do like you can do them in a normal shell script, like using return or exit, or letting the script just run a series of commands and then simply end.

If you want /init to end, you have to pass the responsibility of the init process to another process using exec. See the examples above how exec is used to either run /sbin/init of the mounted root partition or to run a rescue shell in case something went wrong.

Job control

While working with initramfs, especially the Rescue shell, you may come across this message:

/bin/sh: can't access tty; job control turned off

The lack of job control is usually not a problem, since /init is not supposed to be interactive. However, if you want to work with the Busybox shell on a regular basis, being unable to control programs with Ctrl+C or Ctrl+Z can easily become a huge issue. In worst case, if job control is not available, and a program refuses to quit, you have to reboot.

The job control section in the Busybox FAQ offers some help here. You can either use

root #setsid sh -c 'exec sh </dev/tty1 >/dev/tty1 2>&1'

or

root #setsid cttyhack sh

to start a shell on tty1 with job control enabled.

Salvaging

If for whatever reason you lost your /usr/src/initramfs structure, but you still got either the kernel image with the built-in initramfs, or the separate cpio archive, it's possible to salvage it from there. Although it may be easier to just redo it from scratch - if you've done it once, doing it again should be a piece of cake. So this is just in case.

Dismantling the Kernel

You can skip this step if your initramfs is a separate cpio archive already. Otherwise, you'll have to get the built-in cpio archive out of the kernel image. To do that, you have to dismantle it, which isn't easy, since the kernel image is a combination of boot sector and compressed archive itself. It also depends on the compression you are using for your kernel and for your initramfs. For simplicity, this example assumes bzip2 - however, the principle is the same for other compression methods.

The utility of choice when dismantling kernel images is app-misc/binwalk. It analyzes arbitrary files for known signatures, and prints their offsets. While there are usually a bunch of false matches in the output, it should be easy to pick the correct ones.

user $binwalk bzImage

DECIMAL     HEX         DESCRIPTION
-------------------------------------------------------------------------------------------------------------------
15949       0x3E4D      bzip2 compressed data, block size = 900k
3042172     0x2E6B7C    LZMA compressed data, properties: 0x9A, dictionary size: 4194304 bytes, uncompressed size: 9439488 bytes
4433597     0x43A6BD    LZMA compressed data, properties: 0xD8, dictionary size: 16777216 bytes, uncompressed size: 4213785 bytes
8530175     0x8228FF    ELF (NetBSD)

Note
Newer versions also support binwalk --extract which will extract all found offsets directly.

A less sophisticated method would be to use grep to search for signatures. For bzip2, this is BZh. For gzip, use $'\x1f'$'\x8b'.

user $grep -a -b --only-matching BZh bzImage

15949:BZh
3946909:BZh

In this case the offset we are looking for is 15949 bytes. Now you can extract the compressed kernel image:

user $dd if=bzImage bs=15949 skip=1 | bunzip2 > Image

Now, you have the uncompressed kernel image. Somewhere within this image resides the compressed initramfs archive, so just iterate the previous process to find it. Depending on your kernel configuration, you're looking for another bzip2, gzip, or cpio container.

user $

binwalk Image

user $grep -a -b --only-matching BZh Image

Suppose the offset is 171424 bytes this time. Now you can extract the initramfs cpio archive:

user $dd if=Image bs=171424 skip=1 | bunzip2 > initramfs.cpio

If you want to verify that you actually got a cpio archive from that, use the file command:

user $file initramfs.cpio

initramfs.cpio: ASCII cpio archive (SVR4 with no CRC)

Extracting the cpio archive

If your initramfs cpio archive was a separate file, it needs to be uncompressed first.

user $gunzip initramfs.cpio.gz

To extract the uncompressed initramfs.cpio, you can do so with the following command:

Warning
This will overwrite files in your current directory. Do it in /tmp/initramfs/ or similar.

user $cpio -i -d -H newc --no-absolute-filenames < initramfs.cpio

With this, you should have successfully recovered your initramfs structure.

Integrated initramfs does not always update

If your initramfs is integrated into your kernel (instead of using a separate file), there's a possibility that a make bzImage does not actually update it every time. So you might be making changes to your initramfs but actually keep booting using your old, buggy one. In this case you have to manually delete the integrated image to force the kernel to integrate a fresh initramfs archive:

root #rm /usr/src/linux/usr/initramfs_data.cpio*

Alternatively, you could also make clean, but then the entire kernel will need to be recompiled.

Command not found

In Gentoo, busybox is configured as standalone shell by default, which allows busybox to execute its own applets directly. Without this setting, Busybox commands (mkdir, mount, ...) won't work unless there is explicitly a symlink created for them. You can do this at the top of your /init script:

FILE /usr/src/initramfs/initInstall Busybox symlinks to /init

#!/bin/busybox sh

# Install symlinks to all busybox applets first.
/bin/busybox mkdir -p /usr/sbin /usr/bin /sbin /bin
/bin/busybox --install -s

# ...everything else below...

Alternatively, you can create the symlinks directly in /usr/src/initramfs so they will already be included in your initramfs.

root #

mkdir -p /usr/src/initramfs/{usr/sbin,usr/bin,sbin,bin}

root #

chroot /usr/src/initramfs /bin/busybox --install -s

Disappearing root

If your encrypted root (with cryptsetup/LUKS), for example /dev/mapper/gentoo-root, is disappearing after the switch_root command you can recreate the device by entering:

root #

dmsetup mknodes

Variations for switch_root

Some init setups require proc, sys and dev to be mounted before starting up. If you find you are having trouble with switch_root in your initramfs setup try replacing the umount command with a mount --move in your init script.

For example, replace this.

FILE /usr/src/initramfs/initumount commands

# Clean up
umount /proc
umount /sys
umount /dev

# Boot the real thing
exec switch_root /newroot /sbin/init

With this.

FILE /usr/src/initramfs/initmount --move commands

# Clean up
mount --move /proc /newroot/proc
mount --move /sys /newroot/sys
mount --move /dev /newroot/dev

# Boot the real thing
exec switch_root /newroot /sbin/init

Important
umount is used to ensure that "real" init systems, like OpenRC, start in a clean state. You should ideally use umount if it is possible in this circumstance.

Examples

See Custom_Initramfs/Examples for fully functional examples of finished /init scripts.

External resources

Official initramfs documentation locally (less /usr/src/linux/Documentation/filesystems/ramfs-rootfs-initramfs.txt) or online at kernel.org
Linux® From Scratch - About initramfs

Custom Initramfs

Prerequisites

Basics

Directory structure

Device nodes

Applications

Busybox

Init

Packaging

Kernel configuration

Embedding into the Kernel

Creating a separate file

External file list

Finalizing

Functionality

Rescue shell

Dynamic devices

devtmpfs

mdev

Mount by UUID or label

Kernel parameters

LVM

Software RAID

mdadm

DM-Crypt

Encrypted keyfile

Networking

Static IP

DHCP

DNS

Troubleshooting

Static vs. dynamic binaries

lddtree

Kernel panics

Job control

Salvaging

Dismantling the Kernel

Extracting the cpio archive

Integrated initramfs does not always update

Command not found

Disappearing root

Variations for switch_root

Examples

See also

External resources