Docs / mkinitramfs

mkinitramfs

mkinitramfs is Vertex Linux's initramfs generator. It builds a cpio archive compressed with zstd, includes a bundled /init program, adds a userspace backend, copies selected kernel modules, and writes an image named initramfs-linux-<kernel-version>.img.

Applies to Vertex Linux
Primary command mkinitramfs
Related pages Features, Docs index
Note

This page is based on the current mkinitramfs CLI, example config, and bundled init.c. It describes what the tool actually generates today.

Usage

The command takes an optional kernel version. If no version is provided, mkinitramfs uses the running kernel release from /proc/sys/kernel/osrelease or uname -r. 

mkinitramfs
mkinitramfs 6.12.0-vertex
mkinitramfs --module dm_crypt --module ahci
mkinitramfs --no-default-modules --no-auto-root-modules
mkinitramfs --init-bin /usr/libexec/custom-init
Option Purpose
kver Builds for a specific kernel version instead of the running kernel.
--module <MODULE> Adds one or more explicit module requests.
--no-default-modules Disables the built-in default module list.
--no-auto-root-modules Disables automatic detection of root filesystem and storage modules from the host.
--init-bin <PATH> Uses a custom static init binary instead of the installed bundled init.

Image layout

The generator runs a fixed pipeline: it creates the base directory layout, adds the init binary, unpacks the selected backend archive, resolves kernel module dependencies, and finally writes a zstd-compressed cpio image.

The generated archive includes at least the following paths:

  • /init as PID 1 inside the initramfs
  • /etc/initramfs/kernel-version with the target kernel release
  • /etc/initramfs/backend with the selected backend name
  • /etc/initramfs/modules.load listing the module files to load during boot
  • /lib/modules/<kernel-version>/... for copied kernel modules and metadata
Note

Output images are currently written as initramfs-linux-<kernel-version>.img using zstd with checksum support enabled.

Module selection

Module inclusion comes from three sources: a built-in default list, host root auto-detection, and explicit --module arguments. Requests are resolved against modules.dep, dependencies are ordered automatically, and built-in modules are skipped instead of copied.

Default modules

The built-in list includes common storage, filesystem, USB, and virtio drivers such as ahci, sd_mod, nvme, ext4, xfs, btrfs, vfat, virtio_blk, virtio_scsi, and dm_mod.

Automatic root detection

When automatic detection is enabled, mkinitramfs reads the host's mount and block-device state to infer root filesystem and storage drivers. It can add modules based on filesystem type, block-device naming, device-mapper stacks, NVMe, virtio devices, and sysfs driver ownership.

Tip

Use --no-default-modules and --no-auto-root-modules when you want a tightly controlled image and prefer to declare all modules explicitly.

Backend selection

The early userspace tool backend is selected from a simple config file. Valid values are toybox and sbase. If no config file is present, toybox is used by default. 

# mkinitramfs backend selection
# Valid values: toybox, sbase
backend = toybox

The chosen backend determines which prebuilt archive is unpacked into the initramfs. The generator also records the backend name in /etc/initramfs/backend.

Bundled init program

The generated image boots into a bundled C program installed as /init. This program is PID 1 inside the initramfs and is responsible for early mount setup, module loading, root device resolution, root filesystem mounting, and the final switch to the real system init.

The init flow is:

  1. Mount early filesystems such as /proc, /sys, /dev, and /run.
  2. Open /dev/console for stdio.
  3. Parse kernel command line arguments from /proc/cmdline.
  4. Load kernel modules listed in /etc/initramfs/modules.load using finit_module.
  5. Resolve and mount the real root at /new_root.
  6. Move the mount points, clear the old rootfs, chroot, and exec the real init.
Note

If boot fails at any point after early setup, the bundled init records the last error and enters emergency mode rather than panicking immediately.

Kernel parameters

The bundled init parses a small set of kernel arguments directly from /proc/cmdline.

Parameter Purpose
root= Required root device or identifier.
rootfstype= Comma-separated filesystem type list to try when mounting the root.
rootflags= Additional mount options passed to the root filesystem mount.
rootwait Retry root resolution and mount attempts until the device appears.
rw or ro Controls whether the real root is mounted read-write or read-only.
init= Overrides the final init path; otherwise /sbin/init is used.

Root resolution supports direct device paths as well as identifiers such as UUID=, LABEL=, PARTUUID=, and PARTLABEL=. For some filesystems, the bundled init can also fall back to native superblock probing when the usual device symlinks are unavailable.

Emergency mode

On fatal boot errors, the bundled init writes the failure message to /run/initramfs.last_error, sets MKINITRAMFS_LAST_ERROR, and tries to launch an interactive shell from the initramfs environment.

If no usable shell binary is available, it falls back to a built-in rescue REPL with commands such as help, error, cd, pwd, reboot, and poweroff.

Warning

The emergency shell runs as PID 1 in a failed boot environment. It is meant for recovery and inspection, not for normal system use.

See also