initramfs

The initramfs contains all the toolingnecessary programs and codeconfig files needed to bootbring up the system andmachine, mount the root file system toand continuehand fromoff earlythe userspace.rest You can customize it by including kernel modules in it to have them availble inof the boot process asto earlythe asinstalled possiblesystem. (e.g.It btrfs,can amdgpu)be further customized with additional modules, binaries, files and definehooks for special use cases and hardware.

Usage

Automated image generation

Every kernel in Arch Linux comes with its own .preset file stored in /etc/mkinitcpio.d/ with configuration presets for mkinitcpio. Pacman hooks tobuild adda morenew capabilitiesimage toafter earlyevery userspacekernel (e.g.upgrade or installation of a new kernel.

Manual image generation

To manually generate a Linux kernel image issue the following command:

mkinitcpio -p linux

This will generate a new kernel image with the settings of the preset file udev/etc/mkinitcpio.d/linux.preset,.

To generate kernel images with every preset available, pass the systemd-P, argument:

lvm2mkinitcpio -P
,

Configuration

To customize your initramfsinitramfs, editplace drop-in configuration files into /etc/mkinitcpio.conf.d/. They will override the settings in the main configuration file at /etc/mkinitcpio.conf.

An overview of the settings you can customize:

WARNING: Do not use the COMPRESSION_OPTIONS setting, unless you know exactly what you are doing. Misuse can produce unbootable images!

MODULES

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

Here you can specify additional kernel modules needed in early userspace, e.g. file system modules (ext2, reiser4, btrfs), keyboard drivers (usbhid, hid_apple, etc.), USB 3 hubs (xhci_hcd) or "out-of-tree" modules which are not part of the Linux kernel. It is also needed to add modules for hardware devices that are not always connected but you would like to be operational from the very start if they are connected during boot.

*-usb:2
             description: USB controller
             product: Tiger Lake-LP USB 3.2 Gen 2x1 xHCI Host Controller
             vendor: Intel Corporation
             physical id: 14
             bus info: pci@0000:00:14.0
             version: 20
             width: 64 bits
             clock: 33MHz
             capabilities: xhci bus_master cap_list
             configuration: driver=xhci_hcd latency=0
             resources: iomemory:600-5ff irq:163 memory:603f260000-603f26ffff

Example of a MODULES array that adds two modules to the generated image needed for keyboard input, if the keyboard is connected to a USB 3 hub, e.g. a docking station:

MODULES=(xhci_hcd usbhid)

CAUTION: Keep in mind that adding to the initramfs increases the size of the resulting kernel image on disk. Unless you have created your boot partition (more specifically the EFI System partition at either /efi, /boot or /boot/efi) with generous space, you should limit yourself to modules strictly needed for your system. The autodetect hook tries to detect all currently loaded modules of the mostrunning necessary.system to determine the needed modules to include by default. Only include additional modules if something doesn't work as expected.

MODULES=(nvidia nvidia_modeset nvidia_uvm nvidia_drm)

BINARIES

The BINARIES array holds the name of extra executables needed to boot the system. It can also includebe yourused GPU'sto kernelreplace modules:binaries provided by HOOKS. The executable names are sourced from the PATH evironment variable, associated libraries are added as well.

Example of a BINARIES array that adds the kexec binary:

BINARIES=(kexec)

FILES

The FILES array hold the full paths to arbitrary files to be included in the image.

Example of a module configuration file to be included in the image, containting the names of modules to auto-load and optional parameters to pass to them:

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

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. Hooks are referred to by their name, and executed in the order they exist in the HOOKS array of the configuration file.

mkinitcpio -L

The default HOOKS line in /etc/mkinitcpio.conf is as follows:

ATTENTION: The order in which hooks are placed in the array is important!

HOOKS=(base udev autodetect microcode modconf kms keyboard keymap consolefont block filesystems fsck)

This creates a basic image suitable for most single disk systems.

A quick overview of the hooks and their meaning:

busybox

NOTE:By Ifdefault, mkinitcpio will generate a busybox-based initramfs. It starts an init script that scans the filesystem of the initramfs for scripts to execute and bring up the system and hand over the remaining boot process to systemd once the root file system is mounted. This is fine for most use-cases.

For special cases some additional hooks may be required for busybox to bring up the machine properly:

One such special case is encryption, which would result in a HOOKS array that looks like this:

HOOKS=(base udev autodetect microcode modconf kms keyboard keymap consolefont block encrypt filesystems fsck)

ATTENTION: In some cases it might be necessary to place the keyboard hook before the autodetect hook.

MODULES=(btrfsto hid_applebe amdgpu)able HOOKS=(baseto udeventer ...the blockpassphrase lvm2to filesystems)unlock 

Forencrypted file systems, e.g. when using different keyboards requiring a different module from the one in use at the time of building the initramfs.

systemd

If you wish, you can also make systemd bring the whole system up start to finish. In this case bootup will be handled by systemd unit files instead of scripts.

The benefit of this is faster boot times and some additional features not available to a busybox-based initramfsintiramfs.

To instruct mkinitcpio to build a systemd-based initramfs:

HOOKS=(basehook

HOOKS=(basearray udevshould autodetectlook keyboardsomething keymaplike consolefont modconf block encrypt lvm2 filesystems fsck)

HOOKS=(base systemd autodetect microcode modconf kms keyboard sd-vconsole block filesystems fsck)

HOOKS=(base systemd autodetect microcode modconf kms keyboard sd-vconsole block sd-encrypt lvm2 filesystems fsck)

ATTENTION: In some cases it might be necessary to place the keyboard hook before the autodetect hook to be able to enter the passphrase to unlock the encrypted file systems, e.g. when using different keyboards requiring a different module from the one in use at the time of building the initramfs.

COMPRESSION

After configuring yourThe mkinitcpio.confCOMPRESSION option instructs mkinitcpio to yourcompress liking,the re-createresulting images to save on space on the EFI System Partition or /boot partition. This can be especially important if you include a lot of modules and hooks and the size of the image grows.

Compressing the initramfs with:is a tradeoff between:

Which one you choose is something you have to decide on the constraints you're working with (slow/fast CPU, available cores, RAM usage, disk space), but generally speaking the default zstd compression strikes a good balance.

NOTE: See this article for a comprehensive comparison between compression algorithms.

COMPRESSION_OPTIONS

WARNING: Misuse of this option may lead to an unbootable system if the kernel is unable to unpack the resultant archive. Do not set this option unless you're absolutely sure that you have to!

The COMPRESSION_OPTIONS setting allows you to pass additional parameters for the compression tool. Available parameters depend on the algorithm chosen for the COMPRESSION option. Refer to the tool's manual for available options. If left empty mkinitcpio -Pwill make sure it always produces a working image.