My *nix world

Gentoo Initramfs - howto

I have attempted to create a Initramfs file system for my Gentoo kernel in order to use it as a rescue shell whenever I am getting boot problems.

Gentoo have a comprehensive wiki about this but I was unable to make it work by the book. I have tried several times, I have goggled until I forgot what I was looking for, but no result.

Gentoo Initramfs - howto

Finally I succeeded to create a Gentoo Initramfs and I will share the minimal required steps bellow:

  1. Make sure you have busybox compiled as static with the following flags:
    USE="static" emerge --root=/usr/src/initramfs/ -av busybox
  2. create a directory structure as following:
    mkdir /usr/src/initramfs
    cd /usr/src/initramfs
    mkdir -p bin lib dev etc mnt/root proc root sbin sys
  3. copy the minimal device nodes and busybox:
    cp -a /dev/{null,console,tty,sd??} /usr/src/initramfs/dev/
    cp -a /bin/busybox /usr/src/initramfs/bin/busybox
  4. Create the /usr/src/initramfs/init executable file as following:
    #!/bin/busybox sh
    echo "Starting init!"
    rescue_shell() {
        echo "Something went wrong while mounting rootfs. Dropping you to a shell with network support..."
        /bin/busybox --install -s
        # configure the eth0 network interface
        ifconfig eth0
        route add default gw
        # make sure we enable CTRL-C feature
        setsid cttyhack sh
        exec /bin/sh
    # Mount the /proc and /sys filesystems.
    mount -t proc none /proc
    mount -t sysfs none /sys
    mount -t devtmpfs none /dev
    # Do your stuff here.
    echo "Mounting /dev/sda3 root file system..."
    # Mount the root filesystem.
    mount -t ext4 -o ro /dev/sda3 /mnt/root || rescue_shell
    # Clean up.
    umount /proc
    umount /sys
    umount /dev
    # Boot the real thing.
    exec switch_root /mnt/root /sbin/init
  5. Make sure you configure and compile your kernel with the following option:
    General setup --->
    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
  6. Create your initramfs (make sure that /dev/sda1 is mounted as /boot):
    cd /usr/src/initramfs
    find . -print0 | cpio --null -ov --format=newc | gzip -9 > /boot/initramfs.cpio.gz
  7. Edit your /boot/grub/grub.conf layout as following :
    title Gentoo Linux
    root (hd0,0)
    kernel /boot/bzImage
    initrd /boot/initramfs.cpio.gz
  8. Reboot your machine. If something goes wrong when mounting the root partition (eg: /dev/sda3) then you will be dropped directly to the busybox shell.
    You can test this by intentionally changing the /usr/src/initramfs/init line:

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


    mount -o ro /dev/sda9 /mnt/root || rescue_shell.

    When init will try to mount the sda9 invalid partition then the rescue_shell function will be called and then busybox shell will take the control.

Note: anytime you change something in the /usr/src/initramfs/ make sure you re-run the step 6.

That's all folks!

Now, if you think that this article was interesting don't forget to rate it. It shows me that you care and thus I will continue write about these things.

The following two tabs change content below.
Gentoo Initramfs - howto

Eugen Mihailescu

Founder/programmer/one-man-show at Cubique Software
Always looking to learn more about *nix world, about the fundamental concepts of math, physics, electronics. I am also passionate about programming, database and systems administration. 16+ yrs experience in software development, designing enterprise systems, IT support and troubleshooting.
Gentoo Initramfs - howto

Latest posts by Eugen Mihailescu (see all)

One thought on “Gentoo Initramfs - howto

  1. Petros

    Eugen nice article! Do you think you could write an article about initramfs and mounting some Gentoo directories on RAM?

    Let's say /usr/lib64 or something like this.

Leave a Reply

Your email address will not be published. Required fields are marked *