mkinitcpio

Every time a kernel is installed or upgraded, a pacman hook automatically generates a .preset file saved in . For example linux.preset for the official stable kernel package. A preset is simply a list of information required to create initial ramdisk images, instead of manually specifying the various parameters and the location of the output files. By default, it contains the instructions to create two images:

1. the default ramdisk image created following the directives specified in the mkinitcpio #Configuration, and
2. the fallback ramdisk image, same as above except that the autodetect hook is skipped during creation, thus including a full range of modules which supports most systems.

After creating the preset, the pacman hook calls the mkinitcpio script which generates the two images, using the information provided in the preset.

To run the script manually, refer to the mkinitcpio(8) manual page for instructions. In particular, to (re-)generate the preset provided by a kernel package, use the / option followed by the preset to utilize. For example, for the package, use the command:

# mkinitcpio -p linux

To (re-)generate all existing presets, use the / switch. This is typically used to regenerate all the initramfs images after a change of the global #Configuration:

# mkinitcpio -P

Users may create any number of initramfs images with a variety of different configurations. The desired image must be specified in the respective boot loader configuration file.

Users can generate an image using an alternative configuration file. For example, the following will generate an initial ramdisk image according to the directions in and save it as .

# mkinitcpio --config /etc/mkinitcpio-custom.conf --generate /boot/initramfs-custom.img

If generating an image for a kernel other than the one currently running, add the kernel release version to the command line. The installed kernel releases can be found in , the syntax is consistent with the output of the command for each kernel.

# mkinitcpio --generate /boot/initramfs-custom2.img --kernel 5.7.12-arch1-1

As of version 31, mkinitpcio can also create unified kernel images.

The 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.

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

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

BINARIES=(kexec)

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

The 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 array of the configuration file.

The default 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.

Build hooks are found in , custom build hooks can be placed in . These files are sourced by the bash shell during runtime of mkinitcpio and should contain two functions: and help. The function describes the modules, files, and binaries which will be added to the image. An API, documented by mkinitcpio(8), serves to facilitate the addition of these items. The help function outputs a description of what the hook accomplishes.

For a list of all available hooks:

$ mkinitcpio -L

Use mkinitcpio's / option to output help for a specific hook, for example:

$ mkinitcpio -H udev

Runtime hooks are found in /usr/lib/initcpio/hooks/, custom runtime hooks can be placed in . For any runtime hook, there should always be a build hook of the same name, which calls to add the runtime hook to the image. These files are sourced by the busybox ash shell during early userspace. With the exception of cleanup hooks, they will always be run in the order listed in the setting. Runtime hooks may contain several functions:

: Functions of this name will be run once the API file systems have been mounted and the kernel command line has been parsed. This is generally where additional daemons, such as udev, which are needed for the early boot process are started from.

: Functions of this name are run shortly after the early hooks. This is the most common hook point, and operations such as assembly of stacked block devices should take place here.

: Functions of this name are run after the root device has been mounted. This should be used, sparingly, for further setup of the root device, or for mounting other file systems, such as .

: Functions of this name are run as late as possible, and in the reverse order of how they are listed in the array in the configuration file. These hooks should be used for any last minute cleanup, such as shutting down any daemons started by an early hook.

A table of common hooks and how they affect image creation and runtime follows. Note that this table is not complete, as packages can provide custom hooks.

The kernel supports several formats for compression of the initramfs: , , lzma, xz, , and . mkinitcpio uses zstd compressed images by default, note that the zstd compression runs in multi-threading mode (with the -T0 option which spawns as many threads as detected cores).

The provided has the various options commented out. Uncomment one if you wish to switch to another compression method and make sure you have the corresponding compression utility installed. If none is specified, the zstd default method is used. If you wish to create an uncompressed image, specify in the configuration file or use on the command line.

These are additional flags passed to the program specified by , such as:

COMPRESSION_OPTIONS=(-9)

This option can be left empty; mkinitcpio will ensure that any supported compression method has the necessary flags to produce a working image.

With the default zstd compression, to save space for custom kernels (especially with a dual boot setup when using the EFI system partition as ), the --long option is very effective. However, systems with limited RAM may not be able to decompress initramfs using this option. The option may also be desired to see details during the initramfs generation. For example:

COMPRESSION_OPTIONS=(-v -5 --long)

This is the most important parameter specified on the kernel command line, as it determines what device will be mounted as your proper root device. mkinitcpio is flexible enough to allow a wide variety of formats, for example:

root=/dev/sda1                                                # /dev node
root=LABEL=CorsairF80                                         # label
root=UUID=ea1c4959-406c-45d0-a144-912f4e86b207                # UUID
root=PARTUUID=14420948-2cea-4de7-b042-40f67c618660            # GPT partition UUID

If or is specified, init pauses the boot process (after loading hooks, but before mounting the root file system) and launches an interactive shell which can be used for troubleshooting purposes. This shell can be launched after the root has been mounted by specifying . Normal boot continues after exiting from the shell.

Disable hooks at runtime by adding . For example:

disablehooks=resume

Alter the order in which modules are loaded by specifying modules to load early via . (This may be used, for example, to ensure the correct ordering of multiple network interfaces.)

See Boot debugging and mkinitcpio(8) for other parameters.

See RAID#Configure mkinitcpio.

Required packages

requires the  package.

Kernel parameters

Comprehensive and up-to-date information can be found in the official kernel documentation.

ip=

This parameter tells the kernel how to configure IP addresses of devices and also how to set up the IP routing table. It can take up to nine arguments separated by colons: ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:<dns0-ip>:<dns1-ip>:<ntp0-ip>.

If this parameter is missing from the kernel command line, all fields are assumed to be empty, and the defaults mentioned in the kernel documentation apply. In general this means that the kernel tries to configure everything using autoconfiguration.

The parameter can appear alone as the value to the parameter (without all the characters before). If the value is or , no autoconfiguration will take place, otherwise autoconfiguration will take place. The most common way to use this is ip=dhcp.

For parameters explanation, see the kernel documentation.

Examples:

ip=127.0.0.1:::::lo:none  --> Enable the loopback interface.
ip=192.168.1.1:::::eth2:none --> Enable static eth2 interface.
ip=:::::eth0:dhcp --> Enable dhcp protocol for eth0 configuration.

BOOTIF=

If you have multiple network cards, this parameter can include the MAC address of the interface you are booting from. This is often useful as interface numbering may change, or in conjunction with pxelinux IPAPPEND 2 or IPAPPEND 3 option. If not given, will be used.

Example:

BOOTIF=01-A1-B2-C3-D4-E5-F6  # Note the prepended "01-" and capital letters.

nfsroot=

If the parameter is NOT given on the command line, the default will be used.

nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]

Run for parameter explanation.

If your root device is on LVM, see Install Arch Linux on LVM#Adding mkinitcpio hooks.

If using an encrypted root see dm-crypt/System configuration#mkinitcpio for detailed information on which hooks to include.

If you keep as a separate partition, you must adhere to the following requirements:

• Add the hook, mark with a passno of in to run the check on the partition at startup. While recommended for everyone, it is mandatory if you want your partition to be fsck'ed at boot-up. Without this hook, will never be fsck'd.
• If not using the systemd hook, add the hook. This will mount the partition after root is mounted.

If you are curious about what is inside the initramfs image, you can extract it and poke at the files inside of it.

The initramfs image is an SVR4 CPIO archive, generated via the find and commands, optionally compressed with a compression scheme understood by the kernel. For more information on the compression schemes, see #COMPRESSION.

mkinitcpio includes a utility called which will list and/or extract the contents of initramfs images.

You can list the files in the image with:

# lsinitcpio /boot/initramfs-linux.img

And to extract them all in the current directory:

# lsinitcpio -x /boot/initramfs-linux.img

You can also get a more human-friendly listing of the important parts in the image:

# lsinitcpio -a /boot/initramfs-linux.img

Invoke the function of the script with parameters

build_image outfile compression

It can be done by creating a new script with the contents of the function and running it with the above parameters. This will compress the contents present in the current directory in a file named .

The test used by mkinitcpio to determine if is mounted is to see if /dev/fd/ is there. If everything else looks fine, it can be "created" manually by:

# ln -s /proc/self/fd /dev/

(Obviously, must be mounted as well. mkinitcpio requires that anyway, and that is the next thing it will check.)

When initramfs are being rebuilt after a kernel update, you might get warnings:

==> WARNING: Possibly missing firmware for module: module_name

If these messages appear when generating a default initramfs image, then, as the warning says, installing additional firmware may be required. Most common firmware files can be acquired by installing the package. For other packages providing firmware see the table below or try searching for the module name in the official repositories or AUR.

Otherwise, if the messages only appear when generating the fallback initramfs image you have the following options:

• You can safely ignore the warnings, if you know that you do not use the affected hardware.
• If you want to suppress the warnings, you can install the missing firmware. The meta-package contains most optional firmwares. Alternatively, manually install the needed packages:

Module	Package
aic94xx	aic94xx-firmwareAUR
bfa
bnx2x
liquidio
mlxsw_spectrum
nfp
qat_4xxx	Firmware is not yet available.
qed
qla1280
qla2xxx
wd719x
xhci_pci	upd72020x-fwAUR

• If you want to get rid of the warnings, but do not want to waste your system space on unneeded firmware packages, you can disable fallback initramfs generation altogether:
  1. Change line to in all .preset files in /etc/mkinitcpio.d/.
  2. Remove fallback initramfs images: .
  3. Regenerate your bootloader config (e.g. for GRUB: ).

On some motherboards (mostly ancient ones, but also a few new ones), the i8042 controller cannot be automatically detected. It is rare, but some people will surely be without keyboard. You can detect this situation in advance. If you have a PS/2 port and get message, add atkbd to the array.

With an improper initial ram-disk a system often is unbootable. So follow a system rescue procedure like below:

mkinitcpio's hook filters unneeded kernel modules in the primary initramfs scanning /sys and the modules loaded at the time it is run. If you transfer your directory to another machine and the boot sequence fails during early userspace, it may be because the new hardware is not detected due to missing kernel modules. Note that USB 2.0 and 3.0 need different kernel modules.

To fix, first try choosing the fallback image from your bootloader, as it is not filtered by . Once booted, run mkinitcpio on the new machine to rebuild the primary image with the correct modules. If the fallback image fails, try booting into an Arch Linux live CD/USB, chroot into the installation, and run mkinitcpio on the new machine. As a last resort, try manually adding modules to the initramfs.