Difference between revisions of "Mkinitcpio"

From ArchWiki
Jump to: navigation, search
m (Common hooks)
m (See also: simplify link)
 
(205 intermediate revisions by 65 users not shown)
Line 1: Line 1:
 +
{{DISPLAYTITLE:mkinitcpio}}
 
[[Category:Boot process]]
 
[[Category:Boot process]]
 
[[Category:Kernel]]
 
[[Category:Kernel]]
Line 6: Line 7:
 
[[fr:mkinitcpio]]
 
[[fr:mkinitcpio]]
 
[[it:Mkinitcpio]]
 
[[it:Mkinitcpio]]
 +
[[ja:Mkinitcpio]]
 
[[ru:Mkinitcpio]]
 
[[ru:Mkinitcpio]]
 
[[zh-CN:Mkinitcpio]]
 
[[zh-CN:Mkinitcpio]]
{{Article summary start}}
+
{{Related articles start}}
{{Article summary text|A detailed guide to the Arch initramfs creation utility.}}
+
{{Related|systemd}}
{{Article summary heading|Overview}}
+
{{Related|Kernel modules}}
{{Article summary text|{{Boot process overview}}}}
+
{{Related articles end}}
{{Article summary end}}
+
{{DISPLAYTITLE:mkinitcpio}}
+
 
'''mkinitcpio''' is the next generation of [[Wikipedia:initrd|initramfs]] creation.
 
'''mkinitcpio''' is the next generation of [[Wikipedia:initrd|initramfs]] creation.
  
 
== Overview ==
 
== Overview ==
 
 
mkinitcpio is a Bash script used to create an initial ramdisk environment. From the [https://projects.archlinux.org/mkinitcpio.git/tree/man/mkinitcpio.8.txt mkinitcpio man page]:
 
mkinitcpio is a Bash script used to create an initial ramdisk environment. From the [https://projects.archlinux.org/mkinitcpio.git/tree/man/mkinitcpio.8.txt 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.''
+
: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 filesystem and passing control to {{ic|init}}. However, as technology advances, these tasks have become increasingly complex.  
+
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 {{ic|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.  
+
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.  
  
See also: [http://archlinux.me/brain0/2010/02/13/early-userspace-in-arch-linux/ /dev/brain0 » Blog Archive » Early Userspace in Arch Linux].
+
See also: [https://web.archive.org/web/20150430223035/http://archlinux.me/brain0/2010/02/13/early-userspace-in-arch-linux/ /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:
+
mkinitcpio is a modular tool for building an initramfs CPIO image, offering many advantages over alternative methods; these advantages include:
  
 
* The use of [http://www.busybox.net/ BusyBox] to provide a small and lightweight base for early userspace.
 
* The use of [http://www.busybox.net/ 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.
 
* 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.
+
* 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.
+
* 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.
 
* 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 [https://projects.archlinux.org/mkinitcpio.git/ public Git repository].
 
mkinitcpio has been developed by the Arch Linux developers and from community contributions. See the [https://projects.archlinux.org/mkinitcpio.git/ public Git repository].
  
 
== Installation ==
 
== Installation ==
 +
The {{Pkg|mkinitcpio}} package is available in the [[official repositories]] and is a dependency of the {{Pkg|linux}} package.
  
The {{Pkg|mkinitcpio}} package is available in the [[Official_Repositories|official repositories]] and is installed by default as a member of the {{Grp|base}} group.
+
Advanced users may wish to install the latest development version of mkinitcpio from Git with the {{AUR|mkinitcpio-git}} package.
 
+
Advanced users may wish to install the latest development version of mkinitcpio from Git:
+
$ git clone git://projects.archlinux.org/mkinitcpio.git
+
  
 
{{Note|It is '''highly''' recommended that you follow the [https://mailman.archlinux.org/mailman/listinfo/arch-projects arch-projects mailing list] if you use mkinitcpio from Git!}}
 
{{Note|It is '''highly''' recommended that you follow the [https://mailman.archlinux.org/mailman/listinfo/arch-projects arch-projects mailing list] if you use mkinitcpio from Git!}}
  
 
== Image creation and activation ==
 
== Image creation and activation ==
 
 
By default, the mkinitcpio script generates two images after kernel installation or upgrades: {{ic|/boot/initramfs-linux.img}} and {{ic|/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.  
 
By default, the mkinitcpio script generates two images after kernel installation or upgrades: {{ic|/boot/initramfs-linux.img}} and {{ic|/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 [[Boot Loader#Configuration files|configuration file]]. After changes are made to the configuration file, the image must be regenerated. For the stock Arch Linux kernel, {{Pkg|linux}}, this is done by running this command with root privileges:
+
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. After changes are made to the mkinitcpio configuration file, the image must be regenerated. For the stock Arch Linux kernel, the {{Pkg|linux}} package, this is done by running this command with root privileges:
  
 
  # mkinitcpio -p linux
 
  # mkinitcpio -p linux
Line 60: Line 55:
 
{{Warning|''preset'' files are used to automatically regenerate the initramfs after a kernel update; be careful when editing them.}}
 
{{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:
+
=== 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 {{ic|/etc/mkinitcpio-custom.conf}} and save it at {{ic|/boot/linux-custom.img}}.
  
 
  # mkinitcpio -c /etc/mkinitcpio-custom.conf -g /boot/linux-custom.img
 
  # 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 {{ic|/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 {{ic|/usr/lib/modules}}.
  
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-custom2.img -k 3.3.0-ARCH
 
+
  # mkinitcpio -g /boot/linux.img -k 3.3.0-ARCH
+
  
 
== Configuration ==
 
== Configuration ==
 
 
The primary configuration file for '''mkinitcpio''' is {{ic|/etc/mkinitcpio.conf}}. Additionally, preset definitions are provided by kernel packages in the {{ic|/etc/mkinitcpio.d}} directory (e.g. {{ic|/etc/mkinitcpio.d/linux.preset}}).
 
The primary configuration file for '''mkinitcpio''' is {{ic|/etc/mkinitcpio.conf}}. Additionally, preset definitions are provided by kernel packages in the {{ic|/etc/mkinitcpio.d}} directory (e.g. {{ic|/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.}}
 
{{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 {{ic|/etc/mkinitcpio.conf}}. Otherwise, the root device location may change between boots, resulting in kernel panics.
+
{{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 {{ic|/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.
  
A more elegant alternative is to use [[persistent block device naming]] to ensure that the right devices are mounted.}}
+
*'''PS/2 keyboard users''': In order to get keyboard input during early init, if you do not have it already, add the '''keyboard''' hook to the {{ic|HOOKS}}. 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 {{ic|i8042: PNP: No PS/2 controller found. Probing ports directly}} message, add '''atkbd''' to the {{ic|MODULES}}.}}
  
 
Users can modify six variables within the configuration file:
 
Users can modify six variables within the configuration file:
Line 87: Line 81:
 
; {{ic|HOOKS}}: Hooks are scripts that execute in the initial ramdisk.
 
; {{ic|HOOKS}}: Hooks are scripts that execute in the initial ramdisk.
 
; {{ic|COMPRESSION}}: Used to compress the initramfs image.
 
; {{ic|COMPRESSION}}: Used to compress the initramfs image.
; {{ic|COMPRESSION_OPTIONS}}: Command line options to pass to the {{ic|COMPRESSION}} program.
+
; {{ic|COMPRESSION_OPTIONS}}: Extra arguments to pass to the {{ic|COMPRESSION}} program. Usage of this setting is strongly discouraged. mkinitcpio will handle special requirements for compressors (e.g. passing {{ic|1=--check=crc32}} to xz), and misusage can easily lead to an unbootable system.
  
 
=== MODULES ===
 
=== MODULES ===
 
 
The MODULES array is used to specify modules to load before anything else is done.
 
The MODULES array is used to specify modules to load before anything else is done.
  
 
Modules suffixed with a {{ic|?}} 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.
 
Modules suffixed with a {{ic|?}} 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 [[System_Encryption_with_LUKS_for_dm-crypt#Storing_the_Key_File|here]] for more details.}}
+
{{Note|
 +
* If using '''reiser4''', it ''must'' be added to the modules list.
 +
* If you will be needing any file system during the boot process that is not live when you run mkinitcpio — for example, if your LUKS encryption key file is on an '''ext2''' file system but no '''ext2''' file systems are mounted when you run mkinitcpio — that file system module must also be added to the MODULES list. See [[Dm-crypt/System configuration#cryptkey]] for more details.}}
  
 
=== BINARIES and FILES ===
 
=== BINARIES and FILES ===
 
 
These options allow users to add files to the image. Both {{ic|BINARIES}} and {{ic|FILES}} are added before hooks are run, and may be used to override files used or provided by a hook. {{ic|BINARIES}} are auto-located within a standard {{ic|PATH}} and dependency-parsed, meaning any required libraries will also be added. {{ic|FILES}} are added ''as-is''. For example:
 
These options allow users to add files to the image. Both {{ic|BINARIES}} and {{ic|FILES}} are added before hooks are run, and may be used to override files used or provided by a hook. {{ic|BINARIES}} are auto-located within a standard {{ic|PATH}} and dependency-parsed, meaning any required libraries will also be added. {{ic|FILES}} are added ''as-is''. For example:
  
Line 105: Line 99:
 
  BINARIES="kexec"
 
  BINARIES="kexec"
  
=== HOOKS ===
+
For both, {{ic|BINARIES}} and {{ic|FILES}}, multiple entries can be added delimited with spaces.
  
 +
=== HOOKS ===
 
The {{ic|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 {{ic|HOOKS}} setting in the config file.
 
The {{ic|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 {{ic|HOOKS}} setting in the config file.
  
The default {{ic|HOOKS}} setting should be sufficient for most simple, single disk setups. For root devices which are stacked or multi-block devices such as [[LVM]], [[Software_RAID_and_LVM|mdadm]], or [[LUKS]], see the respective wiki pages for further necessary configuration.
+
The default {{ic|HOOKS}} setting should be sufficient for most simple, single disk setups. For root devices which are stacked or multi-block devices such as [[LVM]], [[Software_RAID_and_LVM|mdadm]], or [[dm-crypt]], see the respective wiki pages for further necessary configuration.
  
 
==== Build hooks ====
 
==== Build hooks ====
 
 
Build hooks are found in {{ic|/usr/lib/initcpio/install}}. These files are sourced by the bash shell during runtime of mkinitcpio and should contain two functions: {{ic|build}} and {{ic|help}}. The {{ic|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 {{ic|help}} function outputs a description of what the hook accomplishes.
 
Build hooks are found in {{ic|/usr/lib/initcpio/install}}. These files are sourced by the bash shell during runtime of mkinitcpio and should contain two functions: {{ic|build}} and {{ic|help}}. The {{ic|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 {{ic|help}} function outputs a description of what the hook accomplishes.
  
Line 124: Line 118:
  
 
==== Runtime hooks ====
 
==== Runtime hooks ====
 
 
Runtime hooks are found in {{ic|/usr/lib/initcpio/hooks}}. For any runtime hook, there should always be a build hook of the same name, which calls {{ic|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 {{ic|HOOKS}} setting. Runtime hooks may contain several functions:
 
Runtime hooks are found in {{ic|/usr/lib/initcpio/hooks}}. For any runtime hook, there should always be a build hook of the same name, which calls {{ic|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 {{ic|HOOKS}} setting. Runtime hooks may contain several functions:
  
{{ic|run_earlyhook}}: Functions of this name will be run once the API filesystems 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.
+
{{ic|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.
  
 
{{ic|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.
 
{{ic|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.
  
{{ic|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 filesystems, such as {{ic|/usr}}.
+
{{ic|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 {{ic|/usr}}.
  
 
{{ic|run_cleanuphook}}: Functions of this name are run as late as possible, and in the reverse order of how they are listed in the {{ic|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.
 
{{ic|run_cleanuphook}}: Functions of this name are run as late as possible, and in the reverse order of how they are listed in the {{ic|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.
  
 
==== Common hooks ====
 
==== Common hooks ====
 
 
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.
 
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.
  
{| border="1"  
+
{{Expansion|Find out if {{ic|btrfs}}, {{ic|dmraid}}, {{ic|mdadm}}, {{ic|mdadm_udev}} etc. work/are needed for systemd based initramfs.}}
 +
 
 +
{| class="wikitable"
 
|+ '''Current hooks'''
 
|+ '''Current hooks'''
 
|-
 
|-
! Hook || Installation || Runtime
+
! busybox !! systemd !! Installation !! Runtime
 +
|-
 +
|colspan="2" style="text-align: center;"| '''base''' || Sets up all initial directories and installs base utilities and libraries. Always keep this hook as the first hook unless you know what you are doing. || --
 +
|-
 +
| style="text-align: center;"| '''udev''' ||rowspan="3"  style="text-align: center;"| '''systemd''' || 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 it is recommended.
 +
|-
 +
| style="text-align: center;"| '''usr''' || Add supports for {{ic|/usr}} on a separate partition. || Mounts the {{ic|/usr}} partition after the real root has been mounted.
 
|-
 
|-
| '''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.
+
| style="text-align: center;"| '''resume''' || style="text-align: center;"| -- || Tries to resume from the "suspend to disk" state. Works with both ''swsusp'' and ''[[TuxOnIce]]''. See [[Hibernation]] for further configuration.
 
|-
 
|-
| '''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. || --
+
| style="text-align: center;"| '''btrfs''' || style="text-align: center;"| ''?'' || Sets the required modules to enable [[Btrfs]] for using multiple devices with Btrfs. This hook is not required for using Btrfs on a single device. || Runs {{ic|btrfs device scan}} to assemble a multi-device Btrfs root file system when no udev hook is present. The {{Pkg|btrfs-progs}} package is required for this hook.
 
|-
 
|-
| '''modconf''' || -- || Loads modprobe configuration files from {{ic|/etc/modprobe.d}} and {{ic|/usr/lib/modprobe.d}}
+
|colspan="2" style="text-align: center;"| '''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. || --
 
|-
 
|-
| '''block''' || Adds all block device modules, formerly separately provided by '''fw''', '''mmc''', '''pata''', '''sata''', '''scsi''' , '''usb''' and '''virtio''' hooks. || --
+
|colspan="2" style="text-align: center;"| '''modconf''' || Includes modprobe configuration files from {{ic|/etc/modprobe.d}} and {{ic|/usr/lib/modprobe.d}} || --
 
|-
 
|-
| '''pcmcia''' || Adds the necessary modules for PCMCIA devices. You need to have {{Pkg|pcmciautils}} installed to use this. || --
+
|colspan="2" style="text-align: center;"| '''block''' || Adds all block device modules, formerly separately provided by the ''fw'', ''mmc'', ''pata'', ''sata'', ''scsi'', ''usb'', and ''virtio'' hooks. || --
 
|-
 
|-
| '''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.
+
|colspan="2" style="text-align: center;"| '''pcmcia''' || Adds the necessary modules for PCMCIA devices. You need to have {{Pkg|pcmciautils}} installed to use this. || --
 
|-
 
|-
| '''dmraid''' || Provides support for fakeRAID root devices. You must have {{Pkg|dmraid}} installed to use this. || Locates and assembles fakeRAID block devices using {{ic|mdassemble}}.
+
| style="text-align: center;"| '''net''' || style="text-align: center;"| -- || 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.
 
|-
 
|-
| '''mdadm''' || Provides support for assembling RAID arrays from {{ic|/etc/mdadm.conf}}, or autodetection during boot. You must have {{Pkg|mdadm}} installed to use this. The '''mdadm_udev''' hook is preferred over this hook. || Locates and assembles software RAID block devices using {{ic|mdassemble}}.
+
| style="text-align: center;"| '''dmraid''' || style="text-align: center;"| ''?'' || Provides support for fakeRAID root devices. You must have {{Pkg|dmraid}} installed to use this. Note that it is preferred to use {{ic|mdadm}} with the '''mdadm_udev''' hook with fakeRAID if your controller supports it. || Locates and assembles fakeRAID block devices using {{ic|dmraid}}.
 
|-
 
|-
| '''mdadm_udev''' || Provides support for assembling RAID arrays via udev. You must have {{Pkg|mdadm}} installed to use this. || Locates and assembles software RAID block devices using {{ic|udev}} and {{ic|mdadm}} incremental assembly. This is the preferred method of mdadm assembly (rather than using the above mdadm hook).
+
| style="text-align: center;"| '''mdadm''' || style="text-align: center;"| ''?'' || Provides support for assembling RAID arrays from {{ic|/etc/mdadm.conf}}, or autodetection during boot. You must have {{Pkg|mdadm}} installed to use this. The '''mdadm_udev''' hook is preferred over this hook. || Locates and assembles software RAID block devices using {{ic|mdassemble}}.
 
|-
 
|-
| '''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). || --
+
| style="text-align: center;"| '''mdadm_udev''' || style="text-align: center;"| ''?'' || Provides support for assembling RAID arrays via udev. You must have {{Pkg|mdadm}} installed to use this. If you use this hook with a FakeRAID array, it is recommended to include {{ic|mdmon}} in the binaries section and add the '''shutdown''' hook in order to avoid unnecessary RAID rebuilds on reboot. || Locates and assembles software RAID block devices using {{ic|udev}} and {{ic|mdadm}} incremental assembly. This is the preferred method of mdadm assembly (rather than using the above ''mdadm'' hook).
 
|-
 
|-
| '''keymap''' || Adds keymap and consolefonts from {{ic|/etc/vconsole.conf}}. || Loads the specified keymap and consolefont from {{ic|/etc/vconsole.conf}} during early userspace.
+
|colspan="2" style="text-align: center;"| '''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. || --
 
|-
 
|-
| '''encrypt''' || Adds the {{ic|dm_crypt}} kernel module and the {{ic|cryptsetup}} tool to the image. You must have {{Pkg|cryptsetup}} installed to use this. || Detects and unlocks an encrypted root partition. See [[#Runtime customization]] for further configuration.
+
| style="text-align: center;"| '''keymap''' ||rowspan="2" style="text-align: center;"| '''sd-vconsole''' || Adds the specified keymap(s) from {{ic|/etc/vconsole.conf}} to the initramfs. || Loads the specified keymap(s) from {{ic|/etc/vconsole.conf}} during early userspace.
 
|-
 
|-
| '''lvm2''' || Adds the device mapper kernel module and the {{ic|lvm}} tool to the image. You must have {{Pkg|lvm2}} installed to use this. || Enables all LVM2 volume groups. This is necessary if you have your root filesystem on [[LVM]].
+
| style="text-align: center;"| '''consolefont''' || Adds the specified console font from {{ic|/etc/vconsole.conf}} to the initramfs. || Loads the specified console font from {{ic|/etc/vconsole.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 {{ic|/usr}} partition. || Runs fsck against your root device (and {{ic|/usr}} if separate) prior to mounting.
+
| style="text-align: center;"| '''encrypt''' || style="text-align: center;"| '''sd-encrypt''' || Adds the {{ic|dm_crypt}} kernel module and the {{ic|cryptsetup}} tool to the image. You must have {{Pkg|cryptsetup}} installed to use this. || Detects and unlocks an encrypted root partition. See [[#Runtime customization]] for further configuration.
 +
For '''sd-encrypt''' see {{man|8|systemd-cryptsetup-generator|url=https://www.freedesktop.org/software/systemd/man/systemd-cryptsetup-generator.html}} for available kernel command line options. Alternatively, if the file {{ic|/etc/crypttab.initramfs}} exists, it will be added to the initramfs as {{ic|/etc/crypttab}}. See the {{man|5|crypttab|url=https://www.freedesktop.org/software/systemd/man/crypttab.html}} manpage for more information on crypttab syntax.
 
|-
 
|-
| '''resume''' || -- || Tries to resume from the "suspend to disk" state. Works with both ''swsusp'' and ''[[suspend2]]''. See [[#Runtime customization]] for further configuration.
+
| style="text-align: center;"| '''lvm2''' || style="text-align: center;"| '''sd-lvm2''' || Adds the device mapper kernel module and the {{ic|lvm}} tool to the image. You must have {{Pkg|lvm2}} installed to use this. || Enables all LVM2 volume groups. This is necessary if you have your root file system on [[LVM]].
 
|-
 
|-
| '''filesystems''' || This includes necessary filesystem modules into your image. This hook is '''required''' unless you specify your filesystem modules in MODULES. || --
+
|colspan="2" style="text-align: center;"| '''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 {{ic|/usr}} partition. || Runs fsck against your root device (and {{ic|/usr}} if separate) prior to mounting. The use of this hook requires the rw parameter to be set on the kernel commandline ([https://bbs.archlinux.org/viewtopic.php?pid=1307895#p1307895 discussion]).
 
|-
 
|-
| '''shutdown''' || Adds shutdown initramfs support. Usage of this hook is strongly recommended if you have a separate {{ic|/usr}} partition or encrypted root. || Unmounts and disassembles devices on shutdown.
+
|colspan="2" style="text-align: center;"| '''filesystems''' || This includes necessary file system modules into your image. This hook is '''required''' unless you specify your file system modules in MODULES. || --
 
|-
 
|-
| '''usr''' || Add supports for {{ic|/usr}} on a separate partition. || Mounts the {{ic|/usr}} partition after the real root has been mounted.
+
|style="text-align: center;"| '''shutdown''' ||style="text-align: center;"| '''sd-shutdown''' ||Adds shutdown initramfs support. Usage of this hook was strongly recommended before mkinitcpio 0.16, if you have a separate {{ic|/usr}} partition or encrypted root. From mkinitcpio 0.16 onwards, it is deemed  [https://mailman.archlinux.org/pipermail/arch-dev-public/2013-December/025742.html not necessary]. || Unmounts and disassembles devices on shutdown.
 
|-
 
|-
| '''timestamp''' || Add the {{ic|systemd-timestamp}} binary to the image. Provides support for RD_TIMESTAMP in early userspace. RD_TIMESTAMP can be read by in example {{ic|systemd-analyze}} to determine boot time. || --
 
 
|}
 
|}
 
==== Deprecated hooks ====
 
As of {{Pkg|mkinitcpio}} 0.12.0, the following hooks are deprecated. If you use any of these hooks, you need to replace them with a single instance of the {{ic|block}} hook.
 
 
*{{ic|fw}}
 
*{{ic|mmc}}
 
*{{ic|pata}}
 
*{{ic|sata}}
 
*{{ic|scsi}}
 
*{{ic|usb}}
 
*{{ic|virtio}}
 
 
For more information, you can review Git commit [https://projects.archlinux.org/mkinitcpio.git/commit/?id=97368c0e78f3a4fe4d62f7aedde88d4be13bfdba 97368c0e78] or see the [https://mailman.archlinux.org/pipermail/arch-projects/2012-November/003426.html arch-projects mailing list].
 
  
 
=== COMPRESSION ===
 
=== COMPRESSION ===
 +
The kernel supports several formats for compression of the initramfs—{{pkg|gzip}}, {{pkg|bzip2}}, lzma, {{pkg|xz}} (also known as lzma2), {{pkg|lzo}}, and {{pkg|lz4}}. For most use cases, gzip, lzop, and lz4 provide the best balance of compressed image size and decompression speed. The provided {{ic|mkinitcpio.conf}} has the various {{ic|COMPRESSION}} options commented out. Uncomment one to choose which compression format you desire.
  
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.
+
Specifying no {{ic|COMPRESSION}} will result in a gzip-compressed initramfs file. To create an uncompressed image, specify {{ic|1=COMPRESSION=cat}} in the config or use {{ic|-z cat}} on the command line.
COMPRESSION="gzip"
+
COMPRESSION="bzip2"
+
COMPRESSION="lzma"
+
COMPRESSION="lzop"
+
COMPRESSION="xz"
+
  
Specifying no {{ic|COMPRESSION}} will result in a gzip compressed initramfs file. To create an uncompressed image, specify {{ic|1=COMPRESSION=cat}} in the config or use {{ic|-z cat}} on the command line.
+
Make sure you have the correct file compression utility installed for the method you wish to use.
  
 
=== COMPRESSION_OPTIONS ===
 
=== COMPRESSION_OPTIONS ===
 
 
These are additional flags passed to the program specified by {{ic|COMPRESSION}}, such as:
 
These are additional flags passed to the program specified by {{ic|COMPRESSION}}, such as:
  
 
  COMPRESSION_OPTIONS='-9'
 
  COMPRESSION_OPTIONS='-9'
  
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.
+
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 customization ==
 
== Runtime customization ==
 +
{{Expansion|Which options work with the {{ic|systemd}} hook and which are {{ic|base}}-only?}}
 +
Runtime configuration options can be passed to {{ic|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.
  
Runtime configuration options can be passed to {{ic|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 ===
 
+
=== init ===
+
 
+
{{Note|The following options alter the default behavior of {{ic|init}} in the initramfs environment. See {{ic|/usr/lib/initcpio/init}} for details.}}
+
 
+
 
; {{ic|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, for example:
 
; {{ic|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, for example:
 
  root=/dev/sda1                                                # /dev node
 
  root=/dev/sda1                                                # /dev node
 
  root=LABEL=CorsairF80                                        # label
 
  root=LABEL=CorsairF80                                        # label
 
  root=UUID=ea1c4959-406c-45d0-a144-912f4e86b207                # UUID
 
  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=PARTUUID=14420948-2cea-4de7-b042-40f67c618660            # GPT partition UUID
root=801                                                      # hex-encoded major/minor number
+
  
; {{ic|break}}: If {{ic|<nowiki>break</nowiki>}} or {{ic|<nowiki>break=premount</nowiki>}} is specified, {{ic|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 {{ic|<nowiki>break=postmount</nowiki>}}. Normal boot continues after exiting from the shell.
+
{{Note|The following boot parameters alter the default behavior of {{ic|init}} in the initramfs environment. See {{ic|/usr/lib/initcpio/init}} for details. They will not work when {{ic|systemd}} hook is being used since the {{ic|init}} from {{ic|base}} hook is replaced.}}
  
; {{ic|disablehooks}}: Disable hooks at runtime by adding {{ic|<nowiki>disablehooks=hook1{,hook2,...}</nowiki>}}. For example: {{bc|1=disablehooks=resume}}
+
; {{ic|break}}: If {{ic|break}} or {{ic|1=break=premount}} is specified, {{ic|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 {{ic|1=break=postmount}}. Normal boot continues after exiting from the shell.
  
; {{ic|earlymodules}}: Alter the order in which modules are loaded by specifying modules to load early via {{ic|<nowiki>earlymodules=mod1{,mod2,...}</nowiki>}}. (This may be used, for example, to ensure the correct ordering of multiple network interfaces.)
+
; {{ic|disablehooks}}: Disable hooks at runtime by adding {{ic|1=disablehooks=hook1[,hook2,...]}}. For example: {{bc|1=disablehooks=resume}}
  
; {{ic|rootdelay&#61;N}}: Pause for {{ic|N}} seconds before mounting the root file system by appending {{ic|rootdelay}}. (This may be used, for example, if booting from a USB hard drive that takes longer to initialize.)
+
; {{ic|earlymodules}}: Alter the order in which modules are loaded by specifying modules to load early via {{ic|1=earlymodules=mod1[,mod2,...]}}. (This may be used, for example, to ensure the correct ordering of multiple network interfaces.)
  
See also: [[Boot_Debugging|Debugging with GRUB and init]]
+
See [[Boot debugging]] and [https://projects.archlinux.org/mkinitcpio.git/tree/man/mkinitcpio.8.txt#n212 man mkinitcpio] for other parameters.
  
 
=== Using RAID ===
 
=== Using RAID ===
 +
First, add the {{ic|mdadm_udev}} or {{ic|mdadm}} hook to the {{ic|HOOKS}} array and any required RAID modules (e.g. raid456, ext4) to the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}}.
  
First, add the {{ic|mdadm}} hook to the {{ic|HOOKS}} array and any required RAID modules (raid456, ext4) to the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}}.
+
Using the {{ic|mdadm}} hook, you no longer need to configure your RAID array in the [[kernel parameters]]. The {{ic|mdadm}} hook will either use your {{ic|/etc/mdadm.conf}} file or automatically detect the array(s) during the init phase of boot.
 
+
'''Kernel Parameters: '''
+
Using the {{ic|mdadm}} hook, you no longer need to configure your RAID array in the [[GRUB]] parameters. The {{ic|mdadm}} hook will either use your {{ic|/etc/mdadm.conf}} file or automatically detect the array(s) during the init phase of boot.
+
  
 
Assembly via udev is also possible using the {{ic|mdadm_udev}} hook. Upstream prefers this method of assembly. {{ic|/etc/mdadm.conf}} will still be read for purposes of naming the assembled devices if it exists.
 
Assembly via udev is also possible using the {{ic|mdadm_udev}} hook. Upstream prefers this method of assembly. {{ic|/etc/mdadm.conf}} will still be read for purposes of naming the assembled devices if it exists.
  
 
=== Using net ===
 
=== Using net ===
 
 
{{Warning|NFSv4 is not yet supported.}}
 
{{Warning|NFSv4 is not yet supported.}}
  
'''Required Packages:'''
+
'''Required Packages'''
  
net requires the {{Pkg|mkinitcpio-nfs-utils}} package from the [[Official_Repositories|official repositories]].
+
{{ic|net}} requires the {{Pkg|mkinitcpio-nfs-utils}} package from the [[official repositories]].
  
'''Kernel Parameters:'''  
+
'''Kernel Parameters'''  
  
'''ip='''
+
Comprehensive and up-to-date information can be found in the official [https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt kernel documentation].
  
An interface spec can be either short form, which is just the name of
+
'''ip='''
an interface (''eth0'' or whatever), or long form.  The long form consists
+
 
of up to seven elements, separated by colons:
+
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: {{ic|1=ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:<dns0-ip>:<dns1-ip>}}.
 
+
  ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>
+
  nfsaddrs= is an alias to ip= and can be used too.
+
  
''Parameter explanation:''
+
If this parameter is missing from the kernel command line, all fields are assumed to be empty, and the defaults mentioned in the [https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt kernel documentation] apply. In general this means that the kernel tries to configure everything using autoconfiguration.
  <client-ip>  IP address of the client. If empty, the address will
+
 
                either be determined by RARP/BOOTP/DHCP. What protocol
+
The {{ic|<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".
                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
+
For parameters explanation, see the [https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt kernel doc].
                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
+
                request.
+
 
    
 
    
  <gw-ip>      IP address of a gateway if the server is on a different
+
; Examples
                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
+
                BOOTP/DHCP.
+
 
+
  <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.
+
''Examples:''
+
 
   ip=127.0.0.1:::::lo:none  --> Enable the loopback interface.
 
   ip=127.0.0.1:::::lo:none  --> Enable the loopback interface.
 
   ip=192.168.1.1:::::eth2:none --> Enable static eth2 interface.
 
   ip=192.168.1.1:::::eth2:none --> Enable static eth2 interface.
 
   ip=:::::eth0:dhcp --> Enable dhcp protocol for eth0 configuration.
 
   ip=:::::eth0:dhcp --> Enable dhcp protocol for eth0 configuration.
 +
 +
{{Note|Make sure to use kernel device names (e.g. ''eth0'') for the {{ic|<device>}} parameter, and not [[Network_configuration#Device_names|udev]] ones (e.g. ''enp2s0'') as those will not work.}}
 +
 
'''BOOTIF='''
 
'''BOOTIF='''
  
Line 359: Line 300:
  
 
=== Using LVM ===
 
=== Using LVM ===
 
+
If your root device is on [[LVM]], see [[LVM#Add_lvm2_hook_to_mkinitcpio.conf_for_root_on_LVM|Add lvm2 hook to mkinitcpio.conf for root on 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:
+
 
+
root=/dev/mapper/myvg-root
+
 
+
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:
+
 
+
lvmwait=/dev/mapper/myvg-root
+
 
+
This lets the boot process wait until LVM manages to make the device available.
+
  
 
=== Using encrypted root ===
 
=== Using encrypted root ===
 
+
If using an [[Dm-crypt/Encrypting_an_entire_system|encrypted root]] see [[Dm-crypt/System configuration#mkinitcpio]] for detailed information on which hooks to include.
If your root volume is encrypted, you need to add the {{ic|encrypt}} hook.
+
 
+
For an encrypted root, use something similar to:
+
root=/dev/mapper/root cryptdevice=/dev/sda5:root
+
 
+
In this case, {{ic|/dev/sda5}} is the encrypted device, and we give it an arbitrary name of {{ic|root}}, which means our root device, once unlocked, is mounted as {{ic|/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 ===
 
=== /usr as a separate partition ===
Line 391: Line 309:
 
If you keep {{ic|/usr}} as a separate partition, you must adhere to the following requirements:
 
If you keep {{ic|/usr}} as a separate partition, you must adhere to the following requirements:
  
* Add the {{ic|shutdown}} hook. The shutdown process will pivot to a saved copy of the initramfs and allow for {{ic|/usr}} (and root) to be properly unmounted from the VFS.
+
* Enable {{ic|mkinitcpio-generate-shutdown-ramfs.service}} '''or''' add the {{ic|shutdown}} hook.
 
* Add the {{ic|fsck}} hook, mark {{ic|/usr}} with a {{ic|passno}} of {{ic|0}} in {{ic|/etc/fstab}}. While recommended for everyone, it is mandatory if you want your {{ic|/usr}} partition to be fsck'ed at boot-up. Without this hook, {{ic|/usr}} will never be fsck'd.
 
* Add the {{ic|fsck}} hook, mark {{ic|/usr}} with a {{ic|passno}} of {{ic|0}} in {{ic|/etc/fstab}}. While recommended for everyone, it is mandatory if you want your {{ic|/usr}} partition to be fsck'ed at boot-up. Without this hook, {{ic|/usr}} will never be fsck'd.
* Add the {{ic|usr}} hook. This will mount the {{ic|/usr}} partition after root is mounted. Prior to 0.9.0, mounting of {{ic|/usr}} would be automatic if it was found in the real root's {{ic|/etc/fstab}}.
+
* Add the {{ic|usr}} hook. This will mount the {{ic|/usr}} partition after root is mounted. Prior to 0.9.0, mounting of {{ic|/usr}} would be automatic if it was found in the real root's {{ic|/etc/fstab}}. See [[Fstab]]
  
 
== Troubleshooting ==
 
== Troubleshooting ==
 
 
=== Extracting the image ===
 
=== 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.  
 
If you are curious about what is inside the initrd image, you can extract it and poke at the files inside of it.  
  
Line 414: Line 330:
 
  $ lsinitcpio -a /boot/initramfs-linux.img
 
  $ lsinitcpio -a /boot/initramfs-linux.img
  
== See also ==
+
=== Recompressing a modified extracted image ===
* [[Boot Debugging]] - Debugging with GRUB
+
After extracting an image as explained above, after modifying it, you can find the command necessary to recompress it.  Edit {{ic|/usr/bin/mkinitcpio}} and change the line as shown below (line 531 in mkinitcpio v20-1.)
 +
#MKINITCPIO_PROCESS_PRESET=1 "$0" "${preset_cmd[@]}"
 +
MKINITCPIO_PROCESS_PRESET=1 /usr/bin/bash -x "$0" "${preset_cmd[@]}"
  
== References ==
+
Then running {{ic|mkinitcpio}} with its usual options (typically {{ic|mkinitcpio -p linux}}), toward the last 20 lines or so you will see something like:
 +
+ find -mindepth 1 -printf '%P\0'
 +
+ LANG=C
 +
+ bsdcpio -0 -o -H newc --quiet
 +
+ gzip
  
# Linux Kernel documentation on [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/filesystems/ramfs-rootfs-initramfs.txt;hb=HEAD initramfs]
+
Which corresponds to the command you need to run, which may be:
# Linux Kernel documentation on [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/initrd.txt;hb=HEAD initrd]
+
# find -mindepth 1 -printf '%P\0' | LANG=C bsdcpio -0 -o -H newc --quiet | gzip > /boot/initramfs-linux.img
# Wikipedia article on [http://en.wikipedia.org/wiki/initrd initrd]
+
 
 +
{{Warning|It's a good idea to rename the automatically generated /boot/initramfs-linux.img before you overwrite it, so you can easily undo your changes.  Be prepared for making a mistake that prevents your system from booting.  If this happens, you will need to boot through the fallback, or a boot CD, to restore your original, run mkinitcpio to overwrite your changes, or fix them yourself and recompress the image.}}
 +
 
 +
=== "/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 ===
 +
Using {{ic|systemd/sd-encrypt/sd-lvm2}} '''HOOKS''' instead of the traditional {{ic|encrypt/lvm2/resume}} requires different initrd parameters to be passed by your bootloader. See this post on forum for details [https://bbs.archlinux.org/viewtopic.php?pid=1480241].
 +
 
 +
=== 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 ====
 +
''mkinitcpio'''s {{ic|autodetect}} hook filters unneeded [[kernel modules]] in the primary initramfs scanning {{ic|/sys}} and the modules loaded at the time it is run. If you transfer your {{ic|/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 [[#Image_creation_and_activation|fallback]] image from your [[bootloader]], as it is not filtered by {{ic|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 [[#MODULES|manually]] adding modules to the initramfs.
 +
 
 +
== See also ==
 +
* [[Boot debugging]] - Debugging with GRUB
 +
* Linux Kernel documentation on [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/filesystems/ramfs-rootfs-initramfs.txt?id=HEAD initramfs]
 +
* Linux Kernel documentation on [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/initrd.txt?id=HEAD initrd]
 +
* Wikipedia article on [[wikipedia:initrd|initrd]]
 +
* {{App|[[w:dracut (software)|dracut]]|A cross-distribution initramfs generation tool.|https://dracut.wiki.kernel.org/|{{AUR|dracut}}}}

Latest revision as of 18:04, 27 September 2016

Related articles

mkinitcpio is the next generation of initramfs creation.

Overview

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.

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

Installation

The mkinitcpio package is available in the official repositories and is a dependency of the linux package.

Advanced users may wish to install the latest development version of mkinitcpio from Git with the mkinitcpio-gitAUR package.

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 in the respective boot loader configuration file. After changes are made to the mkinitcpio configuration file, the image must be regenerated. For the stock Arch Linux kernel, the linux package, this is done by running this command with root privileges:

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

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 /boot/linux-custom.img.

# 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 /usr/lib/modules.

# mkinitcpio -g /boot/linux-custom2.img -k 3.3.0-ARCH

Configuration

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.
  • PS/2 keyboard users: In order to get keyboard input during early init, if you do not have it already, add the keyboard hook to the HOOKS. 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.

Users can modify six variables within the configuration file:

MODULES
Kernel modules to be loaded before any boot hooks are run.
BINARIES
Additional binaries to be included in the initramfs image.
FILES
Additional files to be included in the initramfs image.
HOOKS
Hooks are scripts that execute in the initial ramdisk.
COMPRESSION
Used to compress the initramfs image.
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.

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

Note:
  • If using reiser4, it must be added to the modules list.
  • If you will be needing any file system during the boot process that is not live when you run mkinitcpio — for example, if your LUKS encryption key file is on an ext2 file system but no ext2 file systems are mounted when you run mkinitcpio — that file system module must also be added to the MODULES list. See Dm-crypt/System configuration#cryptkey for more details.

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

For both, BINARIES and FILES, multiple entries can be added delimited with spaces.

HOOKS

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

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

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

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

$ mkinitcpio -H udev

Runtime hooks

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

Common hooks

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.

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Find out if btrfs, dmraid, mdadm, mdadm_udev etc. work/are needed for systemd based initramfs. (Discuss in Talk:Mkinitcpio#)
Current hooks
busybox systemd Installation Runtime
base Sets up all initial directories and installs base utilities and libraries. Always keep this hook as the first hook unless you know what you are doing. --
udev systemd 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 it is recommended.
usr Add supports for /usr on a separate partition. Mounts the /usr partition after the real root has been mounted.
resume -- Tries to resume from the "suspend to disk" state. Works with both swsusp and TuxOnIce. See Hibernation for further configuration.
btrfs ? Sets the required modules to enable Btrfs for using multiple devices with Btrfs. This hook is not required for using Btrfs on a single device. Runs btrfs device scan to assemble a multi-device Btrfs root file system when no udev hook is present. The btrfs-progs package is required for this hook.
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 /etc/modprobe.d and /usr/lib/modprobe.d --
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 have pcmciautils installed 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 dmraid installed to use this. Note that it is preferred to use mdadm with the mdadm_udev hook with fakeRAID if your controller supports it. Locates and assembles fakeRAID block devices using dmraid.
mdadm ? Provides support for assembling RAID 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 RAID arrays via udev. You must have mdadm installed to use this. If you use this hook with a FakeRAID array, it is recommended to include mdmon in the binaries section and add the shutdown hook in order to avoid unnecessary RAID rebuilds on reboot. 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).
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 sd-vconsole Adds the specified keymap(s) from /etc/vconsole.conf to the initramfs. Loads the specified keymap(s) from /etc/vconsole.conf during early userspace.
consolefont Adds the specified console font from /etc/vconsole.conf to the initramfs. Loads the specified console font from /etc/vconsole.conf during early userspace.
encrypt sd-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 #Runtime customization for further configuration.

For sd-encrypt see systemd-cryptsetup-generator(8) for available kernel command line options. Alternatively, if the file /etc/crypttab.initramfs exists, it will be added to the initramfs as /etc/crypttab. See the crypttab(5) manpage for more information on crypttab syntax.

lvm2 sd-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 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 /usr partition. Runs fsck against your root device (and /usr if separate) prior to mounting. The use of this hook requires the rw parameter to be set on the kernel commandline (discussion).
filesystems This includes necessary file system modules into your image. This hook is required unless you specify your file system modules in MODULES. --
shutdown sd-shutdown Adds shutdown initramfs support. Usage of this hook was strongly recommended before mkinitcpio 0.16, if you have a separate /usr partition or encrypted root. From mkinitcpio 0.16 onwards, it is deemed not necessary. Unmounts and disassembles devices on shutdown.

COMPRESSION

The kernel supports several formats for compression of the initramfs—gzip, bzip2, lzma, xz (also known as lzma2), lzo, and lz4. For most use cases, gzip, lzop, and lz4 provide the best balance of compressed image size and decompression speed. The provided mkinitcpio.conf has the various COMPRESSION options commented out. Uncomment one to choose which compression format you desire.

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.

Make sure you have the correct file compression utility installed for the method you wish to use.

COMPRESSION_OPTIONS

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

COMPRESSION_OPTIONS='-9'

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 customization

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Which options work with the systemd hook and which are base-only? (Discuss in Talk:Mkinitcpio#)

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

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, 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
Note: The following boot parameters alter the default behavior of init in the initramfs environment. See /usr/lib/initcpio/init for details. They will not work when systemd hook is being used since the init from base hook is replaced.
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 man mkinitcpio for other parameters.

Using RAID

First, add the mdadm_udev or mdadm hook to the HOOKS array and any required RAID modules (e.g. raid456, ext4) to the MODULES array in /etc/mkinitcpio.conf.

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

Using net

Warning: NFSv4 is not yet supported.

Required Packages

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

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

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

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.
Note: Make sure to use kernel device names (e.g. eth0) for the <device> parameter, and not udev ones (e.g. enp2s0) as those will not work.

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

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

root=/dev/nfs

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, see Add lvm2 hook to mkinitcpio.conf for root on LVM.

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:

  • Enable mkinitcpio-generate-shutdown-ramfs.service or add the shutdown hook.
  • 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. See Fstab

Troubleshooting

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

Recompressing a modified extracted image

After extracting an image as explained above, after modifying it, you can find the command necessary to recompress it. Edit /usr/bin/mkinitcpio and change the line as shown below (line 531 in mkinitcpio v20-1.)

#MKINITCPIO_PROCESS_PRESET=1 "$0" "${preset_cmd[@]}"
MKINITCPIO_PROCESS_PRESET=1 /usr/bin/bash -x "$0" "${preset_cmd[@]}"

Then running mkinitcpio with its usual options (typically mkinitcpio -p linux), toward the last 20 lines or so you will see something like:

+ find -mindepth 1 -printf '%P\0'
+ LANG=C
+ bsdcpio -0 -o -H newc --quiet
+ gzip

Which corresponds to the command you need to run, which may be:

# find -mindepth 1 -printf '%P\0' | LANG=C bsdcpio -0 -o -H newc --quiet | gzip > /boot/initramfs-linux.img
Warning: It's a good idea to rename the automatically generated /boot/initramfs-linux.img before you overwrite it, so you can easily undo your changes. Be prepared for making a mistake that prevents your system from booting. If this happens, you will need to boot through the fallback, or a boot CD, to restore your original, run mkinitcpio to overwrite your changes, or fix them yourself and recompress the image.

"/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

Using 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 [1].

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

mkinitcpio's 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.

See also

https://dracut.wiki.kernel.org/ || dracutAUR