knowledge/technology/linux/mkinitcpio.md

obj	arch-wiki	rev
concept	https://wiki.archlinux.org/title/Mkinitcpio	2024-12-16

mkinitcpio

The initial ramdisk is in essence a very small environment (early userspace) which loads various kernel modules and sets up necessary things before handing over control to init. This makes it possible to have, for example, encrypted root file systems and root file systems on a software RAID array. mkinitcpio allows for easy extension with custom hooks, has autodetection at runtime, and many other features.

Configuration

The primary configuration file for mkinitcpio is /etc/mkinitcpio.conf. Additionally, preset definitions are provided by kernel packages in the /etc/mkinitcpio.d directory (e.g. /etc/mkinitcpio.d/linux.preset).

• MODULES : Kernel modules to be loaded before any boot hooks are run.
• BINARIES : Additional binaries to be included in the initramfs image.
• FILES : Additional files to be included in the initramfs image.
• HOOKS : Hooks are scripts that execute in the initial ramdisk.
• COMPRESSION : Used to compress the initramfs image.

MODULES

The MODULES array is used to specify modules to load before anything else is done.

Modules suffixed with a ? will not throw errors if they are not found. This might be useful for custom kernels that compile in modules which are listed explicitly in a hook or configuration file.

BINARIES and FILES

These options allow users to add files to the image. Both BINARIES and FILES are added before hooks are run, and may be used to override files used or provided by a hook. BINARIES are auto-located within a standard PATH and are dependency-parsed, meaning any required libraries will also be added. FILES are added as-is. For example:

FILES=(/etc/modprobe.d/modprobe.conf)

BINARIES=(kexec)

Note that as both BINARIES and FILES are Bash arrays, multiple entries can be added delimited with spaces.

HOOKS

The HOOKS array is the most important setting in the file. Hooks are small scripts which describe what will be added to the image. For some hooks, they will also contain a runtime component which provides additional behavior, such as starting a daemon, or assembling a stacked block device. Hooks are referred to by their name, and executed in the order they exist in the HOOKS array of the configuration file.

The default HOOKS setting should be sufficient for most simple, single disk setups. For root devices which are stacked or multi-block devices such as LVM, RAID, or dm-crypt, see the respective wiki pages for further necessary configuration.

Common Hooks

Hook	Feature
base	Sets up all initial directories and installs base utilities and libraries. Always keep this hook as the first hook unless you know what you are doing, as it provides critical busybox init when not using systemd hook. Optional when using the systemd hook as it only provides a busybox recovery shell.
udev	Adds udevd, udevadm, and a small subset of udev rules to your image.
usr	Adds support for /usr on a separate partition.
resume	Tries to resume from the "suspend to disk" state.
btrfs	Sets the required modules to enable Btrfs for using multiple devices with Btrfs. You need to have btrfs-progs installed to use this. This hook is not required for using Btrfs on a single device.
autodetect	Shrinks your initramfs to a smaller size by creating a whitelist of modules from a scan of sysfs. Be sure to verify included modules are correct and none are missing. This hook must be run before other subsystem hooks in order to take advantage of auto-detection. Any hooks placed before 'autodetect' will be installed in full.
modconf	Includes modprobe configuration files from /etc/modprobe.d/ and /usr/lib/modprobe.d/.
block	Adds all block device modules, formerly separately provided by the fw, mmc, pata, sata, scsi, usb, and virtio hooks.
net	Adds the necessary modules for a network device.
dmraid	Provides support for fakeRAID root devices. You must have dmraid installed to use this. Note that it is preferred to use mdadm with the mdadm_udev hook with fakeRAID if your controller supports it.
keyboard	Adds the necessary modules for keyboard devices. Use this if you have an USB or serial keyboard and need it in early userspace (either for entering encryption passphrases or for use in an interactive shell). As a side effect, modules for some non-keyboard input devices might be added too, but this should not be relied on. Supersedes old usbinput hook.
keymap	Adds the specified keymap(s) from /etc/vconsole.conf to the initramfs. If you use system encryption "Dm-crypt/Encrypting an entire system"), especially full-disk encryption, make sure you add it before the encrypt hook.
encrypt	Adds the dm_crypt kernel module and the cryptsetup tool to the image.
lvm2	Adds the device mapper kernel module and the lvm tool to the image.
fsck	Adds the fsck binary and file system-specific helpers to allow running fsck against your root device (and /usr if separate) prior to mounting. If added after the autodetect hook, only the helper specific to your root file system will be added. Usage of this hook is strongly recommended, and it is required with a separate /usr partition. It is highly recommended that if you include this hook that you also include any necessary modules to ensure your keyboard will work in early userspace.
filesystems	This includes necessary file system modules into your image. This hook is required unless you specify your file system modules in MODULES.

UKI

A Unified Kernel Image (UKI) is a single executable file that can be directly booted by UEFI firmware or automatically sourced by boot-loaders.

In essence, a UKI combines all the necessary components for the operating system to start up, including:

• EFI stub loader
• Kernel command line
• Microcode updates
• Initramfs image (initial RAM file system)
• Kernel image itself
• Splash screen

To enable the UKI edit /etc/mkinitcpio.d/linux.preset:

default_uki="/boot/EFI/Linux/arch-linux.efi"

fallback_uki="/boot/EFI/Linux/arch-linux-fallback.efi"

Build the Unified Kernel Image:

mkinitcpio --allpresets