mkinitcpio is the next generation of initramfs creation.
- 1 Overview
- 2 Installation
- 3 Image creation and activation
- 4 Configuration
- 5 Runtime customization
- 6 Troubleshooting
- 7 See also
mkinitcpio is a Bash script used to create an initial ramdisk environment. From the mkinitcpio man page:
- 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.
Traditionally, the kernel was responsible for all hardware detection and initialization tasks early in the boot process before mounting the root file system and passing control to
init. However, as technology advances, these tasks have become increasingly complex.
Nowadays, the root file system may be on a wide range of hardware, from SCSI to SATA to USB drives, controlled by a variety of drive controllers from different manufacturers. Additionally, the root file system may be encrypted or compressed; within a software RAID array or a logical volume group. The simple way to handle that complexity is to pass management into userspace: an initial ramdisk.
mkinitcpio is a modular tool for building an initramfs CPIO image, offering many advantages over alternative methods; these advantages include:
- The use of BusyBox to provide a small and lightweight base for early userspace.
- Support for udev for hardware auto-detection at runtime, thus preventing the loading of unnecessary modules.
- Using an extendable hook-based init script, which supports custom hooks that can easily be included in pacman packages.
- Support for LVM2, dm-crypt for both legacy and LUKS volumes, mdadm, and swsusp and suspend2 for resuming and booting from USB mass storage devices.
- The ability to allow many features to be configured from the kernel command line without needing to rebuild the image.
mkinitcpio has been developed by the Arch Linux developers and from community contributions. See the public Git repository.
The official repositories and is a dependency of the package.package is available in the
Advanced users may wish to install the latest development version of mkinitcpio from Git with theAUR package.
Image creation and activation
By default, the mkinitcpio script generates two images after kernel installation or upgrades:
/boot/initramfs-linux-fallback.img. The fallback image utilizes the same configuration file as the default image, except the autodetect hook is skipped during creation, thus including a full range of modules. The autodetect hook detects required modules and tailors the image for specific hardware, shrinking the initramfs.
Users may create any number of initramfs images with a variety of different configurations. The desired image must be specified for the bootloader, often in its configuration file. After changes are made to the mkinitcpio configuration file, the image must be regenerated. For the stock Arch Linux kernel, , this is done by running this command with root privileges:
# mkinitcpio -p linux
-p switch specifies a preset to utilize; most kernel packages provide a related mkinitcpio preset file, found in
linux). A preset is a predefined definition of how to create an initramfs image instead of specifying the configuration file and output file every time.
Generate customized manual initcpio
Users can generate an image using an alternative configuration file. For example, the following will generate an initramfs image according to the directions in
/etc/mkinitcpio-custom.conf and save it at
# mkinitcpio -c /etc/mkinitcpio-custom.conf -g /boot/linux-custom.img
If generating an image for a kernel other than the one currently running, add the kernel version to the command line. You can see available kernel versions in
# mkinitcpio -g /boot/linux-custom2.img -k 3.3.0-ARCH
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.
Users can modify six variables within the configuration file:
- Kernel modules to be loaded before any boot hooks are run.
- Additional binaries to be included in the initramfs image.
- Additional files to be included in the initramfs image.
- Hooks are scripts that execute in the initial ramdisk.
- Used to compress the initramfs image.
- Extra arguments to pass to the
COMPRESSIONprogram. Usage of this setting is strongly discouraged. mkinitcpio will handle special requirements for compressors (e.g. passing
--check=crc32to xz), and misusage can easily lead to an unbootable system.
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 config file.
BINARIES and FILES
These options allow users to add files to the image. Both
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 dependency-parsed, meaning any required libraries will also be added.
FILES are added as-is. For example:
FILES, multiple entries can be added delimited with spaces.
HOOKS setting 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 setting in the config file.
HOOKS setting should be sufficient for most simple, single disk setups. For root devices which are stacked or multi-block devices such as LVM, mdadm, or dm-crypt, see the respective wiki pages for further necessary configuration.
Build hooks are found in
/usr/lib/initcpio/install. These files are sourced by the bash shell during runtime of mkinitcpio and should contain two functions:
build 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
-H option to output help for a specific hook, for example:
$ mkinitcpio -H udev
Runtime hooks are found in
/usr/lib/initcpio/hooks. For any runtime hook, there should always be a build hook of the same name, which calls
add_runscript 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
HOOKS setting. 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
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 setting in the config 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.
|base||Sets up all initial directories and installs base utilities and libraries. Always add this hook as the first hook unless you know what you are doing.||--|
|systemd||This will install a basic systemd setup in your initramfs, and is meant to replace the base, usr and udev hooks. Other hooks (like encryption) would need to be ported, and may not work as intended. It is required, if you use any other systemd specific hooks ("sd-*") from below. This hook does not work as intended yet, when combined with lvm2 and may break your boot. Use the sd-lvm2 hook instead of the lvm2 one. You also may wish to still include the base hook (before this hook) to ensure that a rescue shell exists on your initramfs. This hook also installs the service and binary helper needed for resuming from hibernation.||--|
|btrfs||Sets the required modules to enable Btrfs for root and the use of subvolumes.|| Runs |
|udev||Adds udevd, udevadm, and a small subset of udev rules to your image.||Starts the udev daemon and processes uevents from the kernel; creating device nodes. As it simplifies the boot process by not requiring the user to explicitly specify necessary modules, using the udev hook is recommended.|
|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
|block||Adds all block device modules, formerly separately provided by the fw, mmc, pata, sata, scsi, usb, and virtio hooks.||--|
|pcmcia||Adds the necessary modules for PCMCIA devices. You need to haveinstalled to use this.||--|
|net||Adds the necessary modules for a network device. For PCMCIA net devices, please add the pcmcia hook too.||Provides handling for an NFS-based root file system.|
|dmraid|| Provides support for fakeRAID root devices. You must have
installed to use this. Note that it is preferred to use || Locates and assembles fakeRAID block devices using |
|mdadm|| Provides support for assembling RAID arrays from
|| Locates and assembles software RAID block devices using |
|mdadm_udev|| Provides support for assembling RAID arrays via udev. You must have
installed to use this. If you use this hook with a FakeRAID array, it is recommended to include || Locates and assembles software RAID block devices using |
|keyboard||Adds the necessary modules for keyboard devices. Use this if you have an USB 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 to, but this should not be relied on.||--|
|keymap|| Adds the specified keymap(s) from
|| Loads the specified keymap(s) from |
|consolefont|| Adds the specified console font from
|| Loads the specified console font from |
|sd-vconsole|| Adds the keymap(s) and console font specified in
||Loads the specified keymap(s) and console font during early userspace.|
|encrypt|| Adds the
||Detects and unlocks an encrypted root partition. See #Runtime customization for further configuration.|
|sd-encrypt|| This hook allows for an encrypted root device with systemd initramfs.
See the man page of systemd-cryptsetup-generator(8) for available kernel
command line options. Alternatively, if the file
|lvm2|| Adds the device mapper kernel module and the
||Enables all LVM2 volume groups. This is necessary if you have your root file system on LVM.|
|sd-lvm2||Use this hook instead of lvm2 when using the systemd hook||Enables all LVM2 volume groups. This is necessary if you have your root file system on LVM.|
|fsck|| Adds the fsck binary and file system-specific helpers. 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
|| Runs fsck against your root device (and |
|resume||--|| Tries to resume from the "suspend to disk" state. Works with both swsusp and TuxOnIce. See Hibernation for further configuration. Intended to work along with the |
|filesystems||This includes necessary file system modules into your image. This hook is required unless you specify your file system modules in MODULES.||--|
|shutdown|| Adds shutdown initramfs support. Usage of this hook was strongly recommended before mkinitcpio 0.16, if you have a separate
||Unmounts and disassembles devices on shutdown.|
|usr|| Add supports for
|| Mounts the |
The kernel supports several formats for compression of the initramfs -, , lzma, (also known as lzma2), , and . For most use cases, gzip, lzop, and lz4 provide the best balance of compressed image size and decompression speed.
COMPRESSION="gzip" COMPRESSION="bzip2 COMPRESSION="lzma" COMPRESSION="lzop" COMPRESSION="xz" COMPRESSION="lz4"
COMPRESSION will result in a gzip-compressed initramfs file. To create an uncompressed image, specify
COMPRESSION=cat in the config or use
-z cat on the command line.
Make sure you have the correct file compression utility installed for the method you wish to use.
These are additional flags passed to the program specified by
COMPRESSION, such as:
In general these should never be needed as mkinitcpio will make sure that any supported compression method has the necessary flags to produce a working image. Furthermore, misusage of this option can lead to an unbootable system if the kernel is unable to unpack the resultant archive.
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 bootloader. 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
- 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
initpauses 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.
- Disable hooks at runtime by adding
disablehooks=hook1[,hook2,...]. For example:
- 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.)
First, add the
mdadm hook to the
HOOKS array and any required RAID modules (e.g. raid456, ext4) to the
MODULES array in
mdadm hook, you no longer need to configure your RAID array in the kernel parameters. The
mdadm hook will either use your
/etc/mdadm.conf file or automatically detect the array(s) during the init phase of boot.
Assembly via udev is also possible using the
mdadm_udev hook. Upstream prefers this method of assembly.
/etc/mdadm.conf will still be read for purposes of naming the assembled devices if it exists.
net requires the package from the official repositories.
Comprehensive and up-to-date information can be found in the official kernel documentation.
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:
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.
<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 doc.
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.
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.
BOOTIF=01-A1-B2-C3-D4-E5-F6 # Note the prepended "01-" and capital letters.
nfsroot parameter is NOT given on the command line, the default
/tftpboot/%s will be used.
<server-ip> Specifies the IP address of the NFS server. If this field is not given, the default address as determined by the `ip' variable (see below) is used. One use of this parameter is for example to allow using different servers for RARP and NFS. Usually you can leave this blank. <root-dir> Name of the directory on the server to mount as root. If there is a "%s" token in the string, the token will be replaced by the ASCII-representation of the client's IP address. <nfs-options> Standard NFS options. All options are separated by commas. If the options field is not given, the following defaults will be used: port = as given by server portmap daemon rsize = 1024 wsize = 1024 timeo = 7 retrans = 3 acregmin = 3 acregmax = 60 acdirmin = 30 acdirmax = 60 flags = hard, nointr, noposix, cto, ac
If you do not use the
nfsroot parameter, you need to set
root=/dev/nfs to boot from an NFS root via automatic configuration.
Using encrypted root
If using an encrypted root, the
encrypt hook must be added after the
udev hook and before
filesystems and other hooks that may be needed. Specific kernel command line parameters also need to be passed depending on your bootloader: see Dm-crypt/System configuration#mkinitcpio for detailed information.
/usr as a separate partition
If you keep
/usr as a separate partition, you must adhere to the following requirements:
mkinitcpio-generate-shutdown-ramfs.serviceor add the
- Add the
/etc/fstab. While recommended for everyone, it is mandatory if you want your
/usrpartition to be fsck'ed at boot-up. Without this hook,
/usrwill never be fsck'd.
- Add the
usrhook. This will mount the
/usrpartition after root is mounted. Prior to 0.9.0, mounting of
/usrwould be automatic if it was found in the real root's
/etc/fstab. See Fstab
Extracting the image
If you are curious about what is inside the initrd image, you can extract it and poke at the files inside of it.
The initrd image is an SVR4 CPIO archive, generated via the
bsdcpio 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
lsinitcpio which will list and 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
"/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.)
Using systemd HOOKS in a LUKS/LVM/resume setup
systemd/sd-encrypt/sd-lvm2 HOOKS instead of the traditional
encrypt/lvm2/resume requires different initrd parameters to be passed by your bootloader. See this post on forum for details .
Possibly missing firmware for module XXXX
When initramfs are being rebuild after a kernel update, you might get these two warnings:
==> WARNING: Possibly missing firmware for module: aic94xx ==> WARNING: Possibly missing firmware for module: smsmdtv
These appear to any Arch Linux users, especially those who have not installed these firmware modules. If you do not use hardware which uses these firmwares you can safely ignore this message.
Standard rescue procedures
With an improper initial ram-disk a system often is unbootable. So follow a system rescue procedure like below:
Boot succeeds on one machine and fails on another
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.
To fix, first try choosing the fallback image from your bootloader, 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.