mkinitramfs

mkinitramfs [OPTIONS] [VERSION]

-o outfile
    Specifies the output filename for the generated initramfs image. If not provided, it may default to a standard name based on the kernel VERSION.

VERSION
    The kernel version for which the initramfs should be built (e.g., 5.15.0-76-generic). This often determines which modules are included.

-v
    Enables verbose output during the build process, showing details of included modules, binaries, and the steps taken.

-q
    Suppresses non-error output, making the command run quietly.

-d level
    Sets the debug level for more detailed logging. Higher numbers typically mean more debug information (e.g., 0=silent, 1=errors, 2=warnings, 3=info).

-A module
    Forces the inclusion of a specific kernel module, even if not automatically detected as required.

-B module
    Blacklists a kernel module, preventing it from being included in the initramfs image.

-u hook_dir
    Specifies an alternative directory for custom hooks, which are scripts that extend initramfs functionality.

-c config_file
    Specifies an alternative configuration file to override default settings for the initramfs build.

The mkinitramfs command is a utility used to create an initramfs (initial RAM filesystem) image. This image is a gzipped cpio archive containing a minimal root filesystem that is loaded by the Linux kernel very early in the boot process, even before the actual root filesystem is mounted.

The primary purpose of an initramfs is to provide the necessary drivers and utilities required to mount the real root filesystem. This includes drivers for storage controllers (e.g., SATA, NVMe, SCSI), RAID, LVM, and cryptographic disk setups. It typically contains a minimal set of binaries (often provided by BusyBox), libraries, and kernel modules.

mkinitramfs collects these essential components, constructs the cpio archive, and then compresses it. This image is then passed to the kernel by the bootloader (e.g., GRUB). Upon loading, the kernel unpacks the initramfs into a tmpfs (RAM-based filesystem) and executes its /init script, which performs the necessary tasks to locate and mount the root filesystem, finally handing over control to the operating system.

It supersedes the older initrd (initial RAM disk) concept by offering greater flexibility and memory efficiency, as initramfs is unpacked directly into RAM rather than being loop-mounted as a block device.

The behavior and available options of mkinitramfs can vary significantly between Linux distributions, as different distributions use their own implementations (e.g., Debian/Ubuntu's initramfs-tools vs. Red Hat's dracut). Building a custom initramfs incorrectly can result in an unbootable system. Always back up your boot configuration and kernel before making manual changes. It relies on various external tools like cpio, gzip, and a properly configured kernel module environment.

At its core, mkinitramfs gathers specific kernel modules (based on the system's hardware and the target kernel version), essential binaries (like pivot_root, switch_root, and often a BusyBox binary for common utilities), necessary libraries, and, crucially, an /init script. This /init script is the first program the kernel executes once the initramfs is unpacked. It's responsible for tasks like probing for hardware, setting up device-mapper (LVM, cryptsetup) or RAID, mounting the real root filesystem, and then transitioning control to the operating system's main init process (e.g., systemd, SysVinit).

mkinitramfs typically supports a system of 'hooks' – scripts that can be added to extend its functionality. These hooks are executed at various stages during the initramfs build process or at boot time within the initramfs environment. Users can leverage hooks to include additional software, configure special boot options, or provide drivers for unusual hardware not automatically detected, allowing for highly customized boot environments.

The concept of an initial RAM disk (initrd) was introduced in Linux kernel 2.1 to provide a way to load modules needed for mounting the root filesystem. The mkinitrd command was historically used to create these images. With Linux kernel 2.6, initramfs was introduced as a more flexible and memory-efficient successor to initrd. Instead of a loop-mounted block device, initramfs is a cpio archive that is unpacked directly into a tmpfs. The mkinitramfs command emerged as the primary utility to create these new initramfs images, often as part of distribution-specific tools like initramfs-tools (Debian/Ubuntu) or as an alternative to dracut (Red Hat/Fedora), reflecting the shift in boot-time initialization strategy.

update-initramfs(8), dracut(8), mkinitrd(8), lsinitramfs(8), initrd(4), cpio(1), gzip(1)