Arch Linux mkinitcpio: Designing a Minimal initramfs for Reliable Boot

Problem: Boot fails when initramfs lacks required modules

Takeaway: Keep the hook list minimal, verify the generated image, and regenerate it after any kernel or configuration change.

Requirements for a Minimal, Reliable initramfs

• Kernel modules – Only those needed to access the root device and any early‑boot subsystems (e.g., SATA, NVMe, RAID).
• Hooks – An ordered list that brings the root filesystem online, runs needed checks, and provides early user input if required.
• Compression – A supported algorithm; the default xz works on all hardware, while lz4 may be faster on modern CPUs.
• Version consistency – After a kernel upgrade or hook edit, the initramfs must be rebuilt.
• Security boundary – Only trusted kernel modules and official hooks should be included; avoid unvetted AUR hooks unless absolutely necessary.

The Smallest Suitable Design

For a non‑encrypted system with a single disk, the following /etc/mkinitcpio.conf provides a functional early userspace:

# /etc/mkinitcpio.conf – Minimal, functional initramfs
MODULES=""
BINARIES=""
FILES=""
HOOKS="base udev autodetect modconf block filesystems keyboard"
COMPRESSION="xz"

Explanation of each hook:

• base – Core utilities and kernel module handling.
• udev – Device discovery; essential for locating the root block device.
• autodetect – Scans the running system for additional modules needed by the root filesystem.
• modconf – Loads any modules explicitly listed in MODULES (empty here).
• block – Provides generic block‑device support.
• filesystems – Mounts common filesystem types (ext4, btrfs, xfs, etc.).
• keyboard – Allows early keyboard input, useful if a passphrase is needed later.

Trust and Data Boundaries

The initramfs sits between the kernel and the rest of the system. Anything it loads must be trusted:

• Modules that ship with the kernel package.
• Hooks from the official Arch repositories.
• Custom hooks only if they are well‑maintained, signed, and come from a trusted source.

Adding arbitrary binaries or configuration files increases the attack surface without benefit.

Operational Checks and Verification

1. Inspect the current image

Run on the running system:

lsinitcpio /boot/initramfs-linux.img

Confirm that the modules and hooks listed in your mkinitcpio.conf appear in the output.

2. Regenerate after changes

After editing /etc/mkinitcpio.conf you must run:

mkinitcpio -P

The -P flag rebuilds all preset images. Verify that the file was updated by checking its timestamp or size:

stat -c "%y %s" /boot/initramfs-linux.img

3. Boot‑time validation

During boot, watch the early userspace messages. If you see an error about failing to mount the root filesystem or are dropped to an emergency shell, the initramfs is missing a required module or hook.

Common Failure Modes

• Missing block hook – The kernel cannot access block devices, leading to an emergency shell.
• Incorrect hook order – Placing filesystems before block causes filesystem utilities to load before block‑device support.
• Outdated initramfs after kernel upgrade – New kernel modules are absent from the old image, causing a mount failure.
• Untrusted custom hooks – Hooks from the AUR may be poorly maintained and can introduce boot problems or security risks.

Conditions That Would Change the Design

Adjust the minimal hook list only when a new requirement appears:

• Encrypted root (LUKS) – Add encrypt before filesystems and ensure keyboard is present to prompt for the passphrase.
• LVM or RAID – Include lvm2 or mdraid before block.
• Network boot or PXE – Add netboot and network hooks.
• Custom kernel modules – List them in MODULES or rely on modconf to load them.

Each addition increases size and complexity; keep the list as short as possible to preserve reliability and speed.

Practical Example: Adding LUKS Encryption

If the root partition is encrypted with LUKS, the hook list must contain encrypt and keyboard. The updated configuration looks like:

HOOKS="base udev autodetect modconf block encrypt filesystems keyboard"

After saving the file, run mkinitcpio -P. The newly generated initramfs will prompt for the LUKS passphrase during early boot. Verify success by rebooting and observing that the password prompt appears before the root filesystem mounts.

Limitations and Practical Checks

This guide assumes you are using the default mkinitcpio installation from the Arch repositories. It does not cover:

• Custom compression algorithms that require additional user‑space tools.
• Initramfs‑specific debugging shells beyond the standard emergency shell.
• Systems with multiple root devices requiring complex stacking of hooks.

To check that your changes are effective, always:

1. Inspect the image with lsinitcpio.
2. Regenerate with mkinitcpio -P after any edit.
3. Boot and confirm the expected early‑userspace behavior (e.g., password prompt, normal mount).