Skip to content
Browse files

docs: rootfs and kernel img guide

Added a short guide on creating uncompressed kernel and rootfs images
that can be used with Firecracker.

Signed-off-by: Dan Horobeanu <>
  • Loading branch information...
dhrgit authored and acatangiu committed Mar 11, 2019
1 parent d3bfd0f commit 2c375691c9655c5c2b04aaa402d0c7ca74bc8126
Showing with 138 additions and 0 deletions.
  1. +5 −0
  2. +133 −0 docs/
@@ -172,6 +172,11 @@ Issuing a `SendCtrlAltDel` action command through the Firecracker API will gener
`Ctrl + Alt + Del` keyboard event in the guest resulting in a clean reboot on most
guest Linux systems.

### How can I create my own rootfs or kernel images?

Check out our [rootfs and kernel image creation guide](

### We are seeing page allocation failures from Firecracker in the `dmesg` output.

If you see errors like ...
@@ -0,0 +1,133 @@
# Creating Custom rootfs and kernel Images

## Creating a kernel Image

Currently, Firecracker supports only uncompressed, ELF kernel images. You can
build an uncompressed Linux kernel image with:

make vmlinux

Here's a quick step-by-step guide to building your own kernel that Firecracker
can boot:
1. Get the Linux source code:

git clone linux.git
cd linux.git

2. Check out the Linux version you want to build (e.g. we'll be using v4.20

git checkout v4.20

3. You will need to configure your Linux build. You can start from
[our recommended config](../resources/microvm-kernel-config) - just copy
it to `.config` (under the Linux sources dir). You can make interactive
config adjustments using:

make menuconfig

*Note*: there are many ways of building a kernel config file, other than
`menuconfig`. You are free to use whichever one you choose.

4. Build the uncompressed kernel image:

make vmlinux

5. Upon a successful build, you can find the uncompressed kernel image under

## Creating a rootfs Image

A rootfs image is just a file system image, that hosts at least an init
system. For instance, our getting started guide uses an EXT4 FS image with
OpenRC as an init system. Note that, whichever file system you choose to use,
support for it will have to be compiled into the kernel, so it can be mounted
at boot time.

To build an EXT4 image:
1. Prepare a properly-sized file. We'll use 50MiB here, but this depends
on how much data you'll want to fit inside:

dd if=/dev/zero of=/rootfs.ext4 bs=1M count=50

2. Create an empty file system on the file you created:

mkfs.ext4 rootfs.ext4

You now have an empty EXT4 image in `rootfs.ext4`, so let's prepare to
populate it. First, you'll need to mount this new file system, so you
can easily access its contents:

mkdir /tmp/my-rootfs
sudo mount rootfs.ext4 /tmp/my-rootfs

The minimal init system would be just an ELF binary, placed at `/sbin/init`.
The final step in the Linux boot process executes `/sbin/init` and expects it
to never exit. More complex init systems build on top of this, providing
service configuration files, startup / shutdown scripts for various services,
and many other features.

For the sake of simplicity, let's set up an Alpine-based rootfs, with OpenRC
as an init system. To that end, we'll use the official Docker image for
Alpine Linux:
1. First, let's start the Alpine container, bind-mounting the EXT4 image
created earlier, to `/my-rootfs`:

docker run -it --rm -v /tmp/my-rootfs:/my-rootfs alpine

2. Then, inside the container, install the OpenRC init system, and some basic

apk add openrc
apk add util-linux

3. And set up userspace init (still inside the container shell):

# Set up a login terminal on the serial console (ttyS0):
ln -s agetty /etc/init.d/agetty.ttyS0
echo ttyS0 > /etc/securetty
rc-update add agetty.ttyS0 default
# Make sure special file systems are mounted on boot:
rc-update add devfs boot
rc-update add procfs boot
# Then, copy the newly configured system to the rootfs image:
for d in bin etc lib root sbin usr; do tar c "/$d" | tar x -C /my-rootfs; done
mkdir /my-rootfs/{dev,proc,run,sys,var}
# All done, exit docker shell

4. Finally, unmount your rootfs image:

umount /tmp/my-rootfs

You should now have a kernel image (`vmlinux`) and a rootfs image
(`rootfs.ext4`), that you can boot with Firecracker.

0 comments on commit 2c37569

Please sign in to comment.
You can’t perform that action at this time.