Skip to content

gbionescu/build-rootfs

Repository files navigation

Rootfs image builder

This repo builds root filesystem images or initrd images based on Docker containers.

Note: some assembly required.

Images are generated by:

  1. Pulling a base image from Docker Hub.
  2. Installing systemd or any other init system. Alpine uses OpenRC while Amazon Linux and Ubuntu use systemd.
  3. Installs sshd and other utilities to make the image usable.
  4. Sets root:root as the default user and password.
  5. Packs the docker container into a rootfs/initrd image.

See the releases page for pre-built images and kernel.

Prerequisites

Have docker installed.

Building a rootfs

Simply run:

./build-rootfs.sh <rootfs-type>

Where rootfs-type is one of the root filesystem generators that starts with type-.

For example, to generate an alpine rootfs, run:

./build-rootfs.sh alpine

Notes:

  • All images have ssh enabled by default.
  • The default user is root with password root.
  • By default, all images are generated as sparse files.

Building an initrd

The initrd is built using ./build-initrd.sh. By default it's based on the alpine image.

Run with QEMU

To run the generated rootfs with QEMU, run:

./run-qemu.sh rootfs.ext4

This will start a QEMU instance with the rootfs with the following options:

  • no KVM, network, or graphics
  • 1GB of RAM
  • 1 CPU (default)
  • serial console in the terminal
  • uses a kernel image that is built-in to the repo

Customizing the build process

Each rootfs generator consists of 3 files:

  • init-rootfs.sh: creates the root filesystem and formats it. This is needed because a distribution may take a larger amount of space

  • inside-container.sh: what is installed in a rootfs. Here this script usually finishes with copying the rootfs contents to a mounted rootfs.ext4 file.

  • run-container.sh: controls the container lifetime. For example the Ubuntu container is started twice because systemd needs to be initialized.

Adding a new image type

Just add a new folder with the 3 files described above

Tests

Currently the built-in tests build the rootfs for all the types and run them with QEMU.

Tests poll the serial console output for the login: prompt.

To run the tests, simply run:

./tests/test-all.sh

Troubleshooting

  • Need a larger image? Change init-rootfs.sh.
  • Need to install more packages? Change inside-container.sh.