de:Mkinitcpio fr:Mkinitcpio hu:Mkinitcpio ja:Mkinitcpio pt:Mkinitcpio ru:Mkinitcpio zh-hans:Mkinitcpio

mkinitcpio is a Bash script used to create initramfs images. There are two distinct approaches how the various tasks during initial ramdisk phase are performed:

1. systemd-based initial RAM file system

2. systemd is already started at the beginning of the initial ramdisk phase. The tasks to be executed are determined by regular systemd unit files. See systemd bootup process.

Pros:

• Tightly integrated with the rest of the systemd ecosystem, leading to a more consistent and streamlined boot process.

• Parallelize certain boot tasks more effectively, potentially leading to faster overall boot times in some scenarios.

• More comprehensive set of features like systemd-cryptsetup-generator with /etc/crypttab.initramfs or GPT partition automounting.

Cons:

• More dependencies and larger size: Generally results in a larger initramfs due to the inclusion of systemd binaries and its dependencies. This can slightly increase boot time.

• Busybox-based initial RAM file system

• An init script is started that in turn scans the filesystem of the initial ramdisk for scripts to be executed (here in this context called runtime hooks).

Pros:

• Lightweight and smaller in size, fewer dependencies.

• The init script and runtime hooks are executed sequentially, making it easier to identify which step caused problems during boot.

The concrete variant is determined by the presence or absence of the systemd hook in the HOOKS array of /etc/mkinitcpio.conf. See #Hook list for more details.

mkinitcpio has been developed by the Arch Linux developers and from community contributions.

Installation

The mkinitcpio package is a dependency of the kernel packages, so most users will already have it installed.

Image creation and activation

Automated generation

Every time a kernel is installed or upgraded, a pacman hook automatically generates a .preset file for the kernel in /etc/mkinitcpio.d/ if one does not already exist. For example linux.preset for the official stable linux 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 only the first image, the second one must be explicitly enabled:

1. The default ramdisk image created following the directives specified in the configuration.

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 image(s), using the information provided in the preset.

Manual generation

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

# mkinitcpio -p linux

To (re-)generate initramfs images based on all existing presets, use the -P/--allpresets 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.

Customized generation

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 /etc/mkinitcpio-custom.conf and save it as /boot/initramfs-custom.img.

# 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 /usr/lib/modules/, the syntax is consistent with the output of the command uname -r for each kernel.

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

Unified kernel images

mkinitcpio can create unified kernel images (UKIs) either by itself or via systemd-ukify. If systemd-ukify is absent or explicitly disabled using --no-ukify, the UKI will be assembled by mkinitcpio itself. Advanced features of ukify will not be available then.

See unified kernel image for details about UKI generation.

Configuration

The primary configuration file for mkinitcpio is /etc/mkinitcpio.conf. Drop-in configuration files are also supported, e.g. /etc/mkinitcpio.conf.d/myhooks.conf (they aren't taken into account if mkinitcpio is called with -c/--config option and/or use a preset containing ALL_config). Additionally, preset definitions are provided by kernel packages in the /etc/mkinitcpio.d directory (e.g. /etc/mkinitcpio.d/linux.preset).

Users can modify seven variables within the configuration file, see mkinitcpio.conf(5) for more details:

1. MODULES: Kernel modules to be loaded before any boot hooks are run.

2. BINARIES: Additional binaries to be included in the initramfs image.

3. FILES: Additional files to be included in the initramfs image.

4. HOOKS: Hooks are scripts that execute in the initial ramdisk.

5. COMPRESSION: Used to compress the initramfs image.

6. COMPRESSION_OPTIONS: Extra arguments to pass to the COMPRESSION program. Usage of this setting is strongly discouraged. mkinitcpio will handle special requirements for compressors (e.g. passing --check=crc32 to xz), and misusage can easily lead to an unbootable system.

7. MODULES_DECOMPRESS: Whether to decompress loadable kernel modules and firmware files or to keep them in their original compressed form.

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 describing what will be added to the initramfs image. Some hooks are accompanied by a so-called runtime hook providing startup functionality, such as starting a daemon, or assembling a stacked block device.

Hooks are referred to by their name, and executed in the order they are listed in the HOOKS array of the configuration file. The recommended order of the hook list should be followed unless you know what you are doing.

The default HOOKS setting should be sufficient for most simple, single disk setups. For root filesystems based on stacked devices or spanning multiple devices such as LVM, RAID, or dm-crypt, see the respective wiki pages for further necessary configuration.

Build hooks

Build hooks (aka install hooks) are shell script files sourced by the bash shell during execution of mkinitcpio and usually contain two functions: build and help. The build function describes the modules, binaries and other files to be added to the initramfs image. An API, documented by mkinitcpio(8), serves to facilitate the addition of these items. The help function outputs a short description about functionality and usage of the hook.

For a list of all available hooks:

$ mkinitcpio -L

Use mkinitcpios -H/--hookhelp option to output help for a specific hook, for example:

$ mkinitcpio -H udev

Build hooks are located in /usr/lib/initcpio/install/, custom build hooks can be placed in /etc/initcpio/install/.

Runtime hooks

Each build hook listed in the HOOKS array may be accompanied by zero or one runtime hook of the same name. Runtime hooks are shell scripts sourced by the busybox ash shell during initramfs phase. They are responsible for startup tasks such as starting a daemon, or assembling a stacked block device. A build hook installs the corresponding runtime hook by calling add_runscript. Runtime hooks may contain several functions:

run_earlyhook: 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.

run_hook: 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.

run_latehook: 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 /usr.

run_cleanuphook: Functions of this name are run as late as possible, and in the reverse order of how they are listed in the HOOKS 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.

With the exception of run_cleanuphook, these functions are executed in the order the corresponding build hooks are listed in the HOOKS array. Runtime hooks are located in /usr/lib/initcpio/hooks/, custom runtime hooks can be placed in /etc/initcpio/hooks/.

Post hooks

Post hooks are shell scripts or executables run after an image has been (re)generated in order to perform additional tasks like signing.

To each executable the following arguments are passed in this order:

1. the kernel used (may be empty in some circumstances);

2. the generated initramfs image;

3. (optional) the generated unified kernel image.

Additionally, the following environment variables are set:

KERNELVERSION the full kernel version.

KERNELDESTINATION the default location where the kernel should be located on order to be booted.

Post hooks are located in /usr/lib/initcpio/post/ (hooks provided by packages) and /etc/initcpio/post/ (custom hooks).

Hook list

A table of hooks and how they affect image creation and runtime follows.

COMPRESSION

The kernel supports several formats for compression of the initramfs: gzip, bzip2, lzma (xz), xz, lzo (lzop), lz4 and zstd. By default mkinitcpio uses zstd compression for kernel version 5.9 and newer and gzip for kernel versions older than 5.9.

The provided mkinitcpio.conf has the various COMPRESSION 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 default method is used. If you wish to create an uncompressed image, specify COMPRESSION=cat in the configuration file or use -z cat on the command line.

COMPRESSION_OPTIONS

These are additional flags passed to the program specified by COMPRESSION, 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 /boot), the --long option is very effective. However, systems with limited RAM may not be able to decompress initramfs using this option. The -v option may also be desired to see details during the initramfs generation. For example:

COMPRESSION="zstd"
COMPRESSION_OPTIONS=(-v -5 --long)

Highest, but slowest, compression can be achieved by using xz with the -9e compression level and also decompressing the loadable kernel modules and firmware:

COMPRESSION="xz"
COMPRESSION_OPTIONS=(-9e)
MODULES_DECOMPRESS="yes"

MODULES_DECOMPRESS

MODULES_DECOMPRESS controls whether the kernel module and firmware files are decompressed during initramfs creation. The default value is no.

Arch compresses its kernel modules and linux-firmware with zstd at level 19. When using a higher compression than that for the initramfs, setting MODULES_DECOMPRESS"yes" will allow to reduce the initramfs size even further. This comes at the expense of increased RAM and CPU usage at early boot which negatively affects systems with limited RAM or weak CPUs since the kernel will spend more time to decompress the whole initramfs image than it would take to decompress the individual modules and firmware upon loading them.

Runtime customization

Runtime configuration options can be passed to init and certain hooks via the kernel command line. Kernel command-line parameters are often supplied by the boot loader. The options discussed below can be appended to the kernel command line to alter default behavior. See Kernel parameters and Arch boot process for more information.

init from base hook

1. root: 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; see Persistent block device naming#Kernel parameters for examples.

1. break: If break or break=premount 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 break=postmount. Normal boot continues after exiting from the shell.

   disablehooks: Disable hooks at runtime by adding disablehooks=hook1[,hook2,...]. For example:

   disablehooks=resume

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

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

Using RAID

See RAID#Configure mkinitcpio.

Using net

Required packages

net requires the mkinitcpio-nfs-utils 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 <autoconf> parameter can appear alone as the value to the ip parameter (without all the : characters before). If the value is ip=off or ip=none, 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, eth0 will be used.

Example:

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

nfsroot=

If the nfsroot parameter is NOT given on the command line, the default /tftpboot/%s will be used.

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

Run mkinitcpio -H net for parameter explanation.

Using LVM

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

Using encrypted root

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

/usr as a separate partition

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

• Add the fsck hook, mark /usr with a passno of 2 in /etc/fstab to run the check on the partition at startup. While recommended for everyone, it is mandatory if you want your /usr partition to be fsck'ed at boot-up. Without this hook, /usr will never be fsck'd.

• If not using the systemd hook, add the usr hook. This will mount the /usr partition after root is mounted.

Tips and tricks

Fallback initramfs generation

Fallback initramfs generation is disabled by default. To enable it:

Adjust the respective .preset files in /etc/mkinitcpio.d/

• Disable PRESETS=('default') and enable PRESETS=('default' 'fallback') instead

• Enable fallback_image="/boot/initramfs-linux-fallback.img"

• Enable fallback_options="--skiphooks autodetect"

• Regenerate initramfs

• Update your boot loader configuration.

Troubleshooting

Extracting the image

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 bsdcpio commands, optionally compressed with a compression scheme understood by the kernel. For more information on the compression schemes, see #COMPRESSION.

The mkinitcpio package includes a utility called lsinitcpio(1) 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 --extract /boot/initramfs-linux.img

You can also get a human-friendly listing of the important parts of the image (kernel version, early CPIO presence, included modules and binaries, etc.):

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

Recompressing a modified extracted image

Invoke the build_image function of the /usr/bin/mkinitcpio script with parameters

build_image outfile compression

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

"/dev must be mounted" when it already is

The test used by mkinitcpio to determine if /dev 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, /proc must be mounted as well. mkinitcpio requires that anyway, and that is the next thing it will check.)

Possibly missing firmware for module XXXX

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 linux-firmware 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 mkinitcpio-firmware contains most optional firmwares. Alternatively, manually install the needed packages:

• {| class="wikitable"

|- ! Module !! Package |- | aic94xx || aic94xx-firmware |- | ast || ast-firmware |- | bfa || linux-firmware-qlogic |- | bnx2x || linux-firmware-broadcom |- | liquidio || linux-firmware-liquidio |- | mlxsw_spectrum || linux-firmware-mellanox |- | nfp || linux-firmware-nfp |- | qat_420xx || linux-firmware-intel |- | qed || linux-firmware-qlogic |- | qla1280 || linux-firmware-qlogic |- | qla2xxx || linux-firmware-qlogic |- | wd719x || wd719x-firmware |- | xhci_pcixhci_pci_renesas || upd72020x-fw |}

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

For unavailable firmware, you can suppress the warnings by creating dummy files, e.g.:

# echo 'Silence the "Possibly missing firmware for module" message' \
    | tee /usr/lib/firmware/qat_6xxx{,_mmp}.bin >/dev/null

No PS/2 controller found

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 i8042: PNP: No PS/2 controller found. Probing ports directly message, add atkbd to the MODULES array.https://archlinux.org/news/linux-313-warning-ps2-keyboard-support-is-now-modular/

Boot succeeds on one machine and fails on another

mkinitcpios autodetect 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 /boot 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 boot loader, as it is not filtered by autodetect. 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.

Cannot open access to console, the root account is locked

The systemd hook disables the root account. To enable the emergency shell, temporarily add SYSTEMD_SULOGIN_FORCE1 to the kernel parameters.

Alternatively, you can use initcpio-hook-shadowcopy, by installing it and adding the shadowcopy hook after systemd in /etc/mkinitcpio.conf, and regenerating initramfs with mkinitcpio -P. More documentation is available in its GitHub repo.

See also

• Linux Kernel documentation on initramfs, "What is rootfs?"

• Linux Kernel documentation on initrd

• Wikipedia article on initrd