From ArchWiki
Revision as of 09:34, 28 October 2012 by Nonix (talk | contribs) (HOOKS: expand autodetect hook / explain disk encryption and switch to LVM on LUKS / add usb and firewire root / pata and scsi can get removed from fallback if not needed)
Jump to: navigation, search

zh-CN:Mkinitcpio Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary text Template:Article summary end

mkinitcpio is the next generation of initramfs creation.


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 filesystems and root filesystems 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 filesystem and passing control to init. However, as technology advances, these tasks have become increasingly complex.

Nowadays, the root filesystem 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 filesystem 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.

See also: /dev/brain0 » Blog Archive » Early Userspace in Arch Linux.

mkinitcpio is a modular tool for building an initramfs CPIO image, offering many advantages over alternative methods, including:

  • 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.
  • Being an extendable hook-based init script, custom hooks 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.
  • Support for the inclusion of the image in a kernel, thus making a self-contained kernel image possible.

mkinitcpio has been developed by the Arch Linux developers and from community contributions. See the public Git repository.


The mkinitcpio package is available in the official repositories and is installed by default as a member of the base group.

Advanced users may wish to install the latest development version of mkinitcpio from Git:

$ git clone git://
Note: It is highly recommended that you follow the arch-projects mailing list if you use mkinitcpio from Git!

Image creation and activation

By default, the mkinitcpio script generates two images after kernel installation or upgrades: /boot/initramfs-linux.img and /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 configuration file, the image must be regenerated. For the stock Arch Linux kernel, linux, this is done by running this command as root: mkinitcpio -p linux.

The -p switch specifies a preset to utilize; most kernel packages provide a related mkinitcpio preset file, found in /etc/mkinitcpio.d (e.g. /etc/mkinitcpio.d/linux.preset for 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.

Warning: preset files are used to automatically regenerate the initramfs after a kernel update; be careful when editing them.

Users can manually create an image using an alternate configuration file:

# mkinitcpio -c /etc/mkinitcpio-custom.conf -g /boot/linux-custom.img

This will generate the initramfs image for the currently running kernel and save it at /boot/linux-custom.img.

If creating an image for a kernel other than the one currently running, add the kernel version to the command line:

# mkinitcpio -g /boot/linux.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. /etc/mkinitcpio.d/linux.preset).

Warning: lvm2, mdadm, and encrypt are NOT enabled by default. Please read this section carefully for instructions if these hooks are required.
Note: Users with multiple hardware disk controllers that use the same node names but different kernel modules (e.g. two SCSI/SATA or two IDE controllers) should ensure the correct order of modules is specified in /etc/mkinitcpio.conf. Otherwise, the root device location may change between boots, resulting in kernel panics. A more elegant alternative is to use persistent block device naming to ensure that the right devices are mounted.

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.
Command line options to pass to the COMPRESSION program.


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.

Note: If using reiser4, it must be added to the modules list. Additionally, if you'll be needing any filesystem during the boot process that isn't live when you run mkinitcpio—for example, if your LUKS encryption key file is on an ext2 filesystem but no ext2 filesystems are mounted when you run mkinitcpio—that filesystem module must also be added to the MODULES list. See here for more details.


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 dependency-parsed, meaning any required libraries will also be added. FILES are added as-is. For example:



A hook is a script that executes in the initial ramdisk. Hooks are found within the /usr/lib/initcpio/install directory; for a list of available hooks:

$ mkinitcpio -L

Use mkinitcpio's -H option to output help for a specific hook. For example, to display information about the base hook:

$ mkinitcpio -H base

Hooks are listed in order of execution, and are used to add files or modules to the image. Thus, hooks can affect installation (when mkinitcpio is run to generate the image) and/or runtime (via an included script that is run during boot). Scripts can be found within the /usr/lib/initcpio/hooks directory.

The default configuration will work for most users with a standard setup:

HOOKS="base udev autodetect pata scsi sata filesystems"

The autodetect hook will not detect additional modules but shrink the initramfs from all unneeded modules loaded by hooks listed after itself.

The fallback boot option in grub is booting initramfs-linux-fallback.img that is generated without running the autodetect hook. If using the image on more than one machine remove the autodetect hook, so the main initramfs is not tailored to the build machine (will be identical to fallback):

Tango-edit-cut.pngThis section is being considered for removal.Tango-edit-cut.png

Reason: Removing a hook from the line does not need an example as explanation. (Discuss in Talk:Mkinitcpio#)
HOOKS="base udev pata scsi sata filesystems"

If booting root from pata or scsi devices is not required obviously their hooks can safely be deleted so they won't appear in fallback either.

For root on a usb or fw (FireWire) device add them before filesystems.

As mentioned above hooks are executed in the order they are listed here. As many hooks depend on each other (at runtime) the wrong order can leave the system unbootable.

In example for a lvm2 root volume on an encrypted device it is important that the encryption is mapped before any lvm volume groups can be found and filesystems are mounted. As well the (optional) keymap hook is needed before entering the passphrase.

HOOKS="base udev autodetect pata scsi sata (keymap) encrypt lvm2 filesystems (shutdown)"

A table of common hooks and their function follows. Note that this table is not complete, as packages can provide custom hooks.

Common hooks
Hook Installation Runtime
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. --
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. --
pata Adds the libata/PATA modules to the image. Use this if your root device is on a PATA or IDE disk. Also use the autodetect hook if you want to minimize your image size --
mmc Adds MMC modules to the image. Use this if your root device is on a MultiMediaCard such as CompactFlash. Also use the autodetect hook if you want to minimize your image size --
sata Adds serial ATA modules to the image. Use this if your root device is on a SATA disk. Also use the autodetect hook if you want to minimize your image size. --
scsi Adds SCSI modules to the image. Use this if your root device is on a SCSI disk. Also use the autodetect hook if you want to minimize your image size. --
usb Adds USB modules to the image. Use this if your root device is on a USB mass storage device or if your USB mass storage device needs to be accessed otherwise (checked, mounted, etc.) at boot time. --
usbinput Adds USB HID modules to the image. 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). --
fw Adds FireWire modules to the image. Use this if your root device is on a FW mass storage device. --
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 filesystem.
pcmcia Adds the necessary modules for PCMCIA devices. You need to have pcmciautils installed to use this. --
filesystems This includes necessary filesystem modules into your image. This hook is required unless you specify your filesystem modules in MODULES. --
lvm2 Adds the device mapper kernel module and the lvm tool to the image. You must have lvm2 installed to use this. Enables all LVM2 volume groups. This is necessary if you have your root filesystem on LVM.
dmraid Providers support for fakeRAID root devices. You must have dmraid installed to use this. Locates and assembles fakeRAID block devices using mdassemble.
mdadm Provides support for assembling the arrays from /etc/mdadm.conf, or autodetection during boot. You must have mdadm installed to use this. The mdadm_udev hook is preferred over this hook. Locates and assembles software RAID block devices using mdassemble.
mdadm_udev Provides support for assembling the arrays via udev. Locates and assembles software RAID block devices using udev and mdadm incremental assembly. This is the preferred method of mdadm assembly (rather than using the above mdadm hook).

You must have mdadm installed to use this.

encrypt Adds the dm_crypt kernel module and the cryptsetup tool to the image. You must have cryptsetup installed to use this. Detects and unlocks an encrypted root partition. See #Using encrypted root for further configuration.
resume -- Tries to resume from the "suspend to disk" state. Works with both swsusp and suspend2. See #Runtime customization for further configuration.
keymap Adds keymap and consolefonts from rc.conf. Loads the specified keymap and consolefont from rc.conf during early userspace.
fsck Adds the fsck binary and filesystem-specific helpers. If added after the autodetect hook, only the helper specific to your root filesystem will be added. Usage of this hook is strongly recommended, and it is required with a separate /usr partition. Runs fsck against your root device (and /usr if separate) prior to mounting.
shutdown Adds shutdown initramfs support. Usage of this hook is strongly recommended if you have a separate /usr partition or encrypted root. Unmounts and disassembles devices on shutdown.
usr Add supports for /usr on a separate partition. Mounts the /usr partition after the real root has been mounted.
timestamp Provides support for RD_TIMESTAMP in early userspace. RD_TIMESTAMP can be read by a program such as systemd-analyze to determine boot time.

Creating a custom hook

An initcpio hook is just another shell script containing necessary information pointing mkinitcpio which executables should be loaded and with what options. It can be useful in some rare occasions when something is needed in early or late userspace, when not provided by other already installed scripts.

First create the actual script:

 build() {
     add_binary /bin/bash  #/bin/bash is given as an example, you can type your desired executable here
     add_runscript  # will determine the name of the script, and add appropriately from /usr/lib/initcpio/hooks
 help() {
     cat <<HELPEOF
     Line used as help information #Typing mkinitcpio -H hook will display this information

Now create the actual hook:

 run_hook ()
     msg -n ":: This is an example hook"
     bash #your executable example
     msg "done."
Note: It is neither necessary, nor advisable, to make either of the two scripts executable.

Now edit /etc/mkinitcpio.conf accordingly to include your custom hook. You can also include it in /etc/rc.sysinit to load it in late userspace.


The kernel supports several formats for compression of the initramfs - gzip, bzip2, lzma, xz (also known as lzma2), and lzo. For most use cases, gzip or lzop provide the best balance of compressed image size and decompression speed.

COMPRESSION="bzip2"     # requires kernel 2.6.30
COMPRESSION="lzma"      # requires kernel 2.6.30
COMPRESSION="lzop"      # requires kernel 2.6.34
COMPRESSION="xz"        # requires kernel 2.6.38

Specifying no 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.


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.

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


Note: The following options alter the default behavior of init in the initramfs environment. See /usr/lib/initcpio/init for details.
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=/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0-part1    # udev symlink (requires the udev hook)
root=801                                                      # hex-encoded major/minor number
If break or break=premount is specified, init pauses the boot process (after loading hooks, but before mounting the root filesystem) 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.)
Pause for N seconds before mounting the root file system by appending rootdelay. (This may be used, for example, if booting from a USB hard drive that takes longer to initialize.)

See also: Debugging with GRUB and init

Using RAID

First, add the mdadm hook to the HOOKS array and any required RAID modules to the MODULES array in /etc/mkinitcpio.conf.

Kernel Parameters: Using the mdadm hook, you no longer need to configure your RAID array in the GRUB 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.

Using net

Required Packages:

net requires the mkinitcpio-nfs-utils package from the official repositories.

Kernel Parameters:


An interface spec can be either short form, which is just the name of an interface (eth0 or whatever), or long form. The long form consists of up to seven elements, separated by colons:

 nfsaddrs= is an alias to ip= and can be used too.

Parameter explanation:

 <client-ip>   IP address of the client. If empty, the address will
               either be determined by RARP/BOOTP/DHCP. What protocol
               is used depends on the <autoconf> parameter. If this
               parameter is not empty, autoconf will be used.
 <server-ip>   IP address of the NFS server. If RARP is used to
               determine the client address and this parameter is NOT
               empty only replies from the specified server are
               accepted. To use different RARP and NFS server,
               specify your RARP server here (or leave it blank), and
               specify your NFS server in the `nfsroot' parameter
               (see above). If this entry is blank the address of the
               server is used which answered the RARP/BOOTP/DHCP
 <gw-ip>       IP address of a gateway if the server is on a different
               subnet. If this entry is empty no gateway is used and the
               server is assumed to be on the local network, unless a
               value has been received by BOOTP/DHCP.
 <netmask>     Netmask for local network interface. If this is empty,
               the netmask is derived from the client IP address assuming
               classful addressing, unless overridden in BOOTP/DHCP reply.
 <hostname>    Name of the client. If empty, the client IP address is
               used in ASCII notation, or the value received by
 <device>      Name of network device to use. If this is empty, all
               devices are used for RARP/BOOTP/DHCP requests, and the
               first one we receive a reply on is configured. If you
               have only one device, you can safely leave this blank.
 <autoconf>	Method to use for autoconfiguration. If this is either
               'rarp', 'bootp', or 'dhcp' the specified protocol is
               used.  If the value is 'both', 'all' or empty, all
               protocols are used.  'off', 'static' or 'none' means
               no autoconfiguration.


 ip=  --> Enable the loopback interface.
 ip= --> 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.


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


Parameter explanation:

 <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
 <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 LVM

If your root device is on LVM, you must add the lvm2 hook. You have to pass your root device on the kernel command line in the following format:

root=/dev/mapper/<volume group name>-<logical volume name>

for example:


In addition, if your root device might initialize slowly (e.g. a USB device) and/or you receive a "volume group not found" error during boot, you might need to add the following to the kernel command line:

lvmwait=/dev/mapper/<volume group name><logical volume name>

for example:


This lets the boot process wait until LVM manages to make the device available.

Using encrypted root

If your root volume is encrypted, you need to add the encrypt hook.

For an encrypted root, use something similar to:

root=/dev/mapper/root cryptdevice=/dev/sda5:root

In this case, /dev/sda5 is the encrypted device, and we give it an arbitrary name of root, which means our root device, once unlocked, is mounted as /dev/mapper/root. On bootup, you will be prompted for the passphrase to unlock it.See LUKS#Configuration_of_initcpio for more details about using encrypted root.

/usr as a separate partition

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

  • Add the shutdown hook. The shutdown process will pivot to a saved copy of the initramfs and allow for /usr (and root) to be properly unmounted from the VFS.
  • Add the fsck hook, mark /usr with a passno of 0 in /etc/fstab. 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.
  • Add the usr hook. This will mount the /usr partition after root is mounted. Prior to 0.9.0, mounting of /usr would be automatic if it was found in the real root's /etc/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 find and bsdcpio commands, optionally compressed with a compression scheme understood by the kernel: namely gzip, bzip2, lzma, lzo, or xz.

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

See Also


  1. Linux Kernel documentation on initramfs
  2. Linux Kernel documentation on initrd
  3. Wikipedia article on initrd