Difference between revisions of "Mkinitcpio"
m (→MODULES: modload is gone)
m (mkinitcpio hangs on 'autodetect' during kernel upgrade)
|Line 438:||Line 438:|
== Troubleshooting ==
== Troubleshooting ==
=== Extracting the image ===
=== Extracting the image ===
Revision as of 03:24, 2 March 2010
mkinitcpio is the next generation of initramfs creation.
- The initial ramdisk, [initramfs], or initrd is a temporary file system commonly used in the boot process of the Linux kernel. It is typically used for making preparations before the real root file system can be mounted.
- 1 Overview
- 2 Installation
- 3 Image creation and activation
- 4 Configuration
- 5 Customizing the kernel command line
- 5.1 Entering failsafe mode
- 5.2 Disabling hooks
- 5.3 Blacklisting modules
- 5.4 Using raid
- 5.5 Using net
- 5.6 Using lvm
- 5.7 Using encrypted root
- 5.8 Add a Delay
- 5.9 Example bootloader configuration files
- 6 Troubleshooting
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 Template:Codeline. 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.
mkinitcpio is a modular tool for building an init ramfs cpio image, offering many advantages over alternative methods, including:
- The use of busybox to provide a small and lightweight base for early userspace (prior to version 0.6, klibc was used instead).
- Support for udev for hardware autodetection 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, raid, 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 phrakture and tpowa with some help from the community.
The Template:Package Official package is available in the [core] repository, and is installed by default as a member of the base group:
# pacman -S mkinitcpio
Users may wish to install the latest development version of mkinitcpio from Git:
$ git clone git://projects.archlinux.org/mkinitcpio.git
Image creation and activation
By default, the mkinitcpio script generates two images after kernel installation or upgrades: Template:Filename and Template:Filename. 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 (Template:Filename for GRUB users). After changes are made to the configuration file, the image must be regenerated. For the stock Arch Linux kernel, Template:Package Official, this is accomplished with the command:
# mkinitcpio -p kernel26
The Template:Codeline switch specifies a preset to utilize; most kernel packages provide a related mkinitcpio preset file, found in Template:Filename (e.g. Template:Filename for kernel26). A preset is a predefined definition of how to create an initramfs image instead of specifying the configuration file and output file every time.
Users can manually create an image using an alternate configuration file:
# mkinitcpio -c /etc/mkinitcpio-custom.conf -g /boot/kernel26-custom.img
This will generate the initramfs image for the currently running kernel and save it at Template:Filename.
If creating an image for a kernel other than the one currently running, add the kernel version to the command line:
# mkinitcpio -g /boot/kernel26.img -k 2.6.16-ARCH
Users can modify five 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 intramfs image.
- Hooks are scripts that execute in the initial ramdisk.
- Used to compress the initramfs image.
A hook is a script that executes in the initial ramdisk. Hooks are listed in order of execution, and control the modules and scripts added to the image.
Hooks are found within the Template:Filename directory; for a list of available hooks:
$ ls -1 /lib/initcpio/install
Use mkinitcpio's Template:Codeline option to output help for a specific hook. For example, to display information about the base hook:
$ mkinitcpio -H base
The default configuration will work for most users with a standard setup:
HOOKS="base udev autodetect pata scsi sata filesystems"
If using the image on more than one machine, remove the autodetect hook, which tailors the image to the build machine:
HOOKS="base udev pata scsi sata filesystems"
For support for encrypted volumes on LVM2 volume groups:
HOOKS="base udev autodetect pata scsi sata lvm2 encrypt filesystems"
A table of common hooks and their function follows. Note that this table is not complete, as packages can provide custom hooks.
|base||Sets up all initial directories and installs base utilities and libraries. Always add this hook unless you know what you are doing.||--|
|udev||Adds udev to your image||Udev will be used to create your root device node and detect the needed modules for your root device. As it simplifies things, using the udev hook is recommended.|
|autodetect||Shrinks your initramfs to a smaller size by autodetecting your needed modules. 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.||--|
|ide||Adds legacy IDE modules to the image. You may choose to use this if your root device is on an IDE disk. Also use the autodetect hook if you want to minimize your image size||Loads legacy IDE modules. You will need the udev hook unless you specify the needed modules manually (see MODULES section below).|
|pata||Adds the new libata/PATA IDE modules to the image. Use this if your root device is on a IDE disk. Also use the autodetect hook if you want to minimize your image size||Loads IDE modules. You will need the udev hook unless you specify the needed modules manually (see MODULES section below). PATA is the kernel's new IDE driver. PATA utilizes SCSI emulation and will change Template:Filename to Template:Filename. More information.|
|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.||Loads SATA modules. You will need the udev hook unless you specify the needed modules manually (see MODULES section below).|
|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.||Loads SCSI modules. You will need the udev hook unless you specify the needed modules manually (see MODULES section below).|
|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.||Loads USB modules. You will need the udev hook unless you specify the needed modules manually (see MODULES section below).|
|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 failsafe mode).||Loads USB HID modules. You will need the udev hook unless you specify the needed modules manually (see MODULES section below).|
|fw||Adds FireWire modules to the image. Use this if your root device is on a FW mass storage device.||Loads FW modules. You will need the udev hook unless you specify the needed modules manually (see MODULES section below).|
|net||Adds the necessary modules for a network device. For PCMCIA net devices please add the pcmcia hook too.||Loads network modules. You will need the udev hook unless you specify the needed modules manually (see MODULES section below). See #Customizing the kernel command line for further configuration.|
|pcmcia||Adds the necessary modules for PCMCIA devices. You need to have Template:Package Official installed to use this.||Loads pcmcia modules. You will need the udev hook unless you specify the needed modules manually (see MODULES section below).|
|dsdt||Loads a custom ACPI DSDT file during boot. Place your custom DSDT file for inclusion at Template:Filename||The custom DSDT file is automatically used by the kernel if it is present in initramfs.|
|filesystems||This includes necessary filesystem modules into your image. This hook is required unless you specify your filesystem modules in MODULES.||This will detect the filesystem type at runtime, load the module and pass it to kinit. (Will NOT detect reiser4, which must be added to modules list.)|
|lvm2||Adds the device mapper kernel module and the Template:Codeline tool to the image. You need to have the Template:Package Official package installed to use this.||Enables all LVM2 volume groups. This is necessary if you have your root filesystem on LVM.|
|raid||Adds the modules and Template:Codeline for a software RAID setup. This hook has been superseded by the mdadm hook. You need to have Template:Package Official installed to use this.||Loads the necessary modules for software raid devices, and assembles the raid devices when run. See #Customizing the kernel command line for further configuration.|
|mdadm||This hook supersedes the above raid hook. It supports assembling the arrays from Template:Filename, or autodetection during boot.||Loads the necessary modules for software raid devices, and assembles the raid devices when run. See #Customizing the kernel command line for further configuration.|
|encrypt||Adds the dm-crypt kernel module and the Template:Codeline tool to the image. You need to have the Template:Package Official package installed to use this.||Detects and unlocks an encrypted root partition. See #Customizing the kernel command line for further configuration.|
|resume||--||This tries to resume from the "suspend to disk" state. Works with both swsusp and suspend2. See #Customizing the kernel command line for further configuration.|
|firmware||Adds Template:Filename files.||Loads firmware. You will need the udev hook to get firmware loaded.|
|keymap||Adds keymap and consolefonts from rc.conf.||Loads the specified keymap and consolefont from Template:Filename during early userspace.|
The MODULES array is used to specify modules to load before anything else is done. To accelerate the boot process, users may opt to disable the udev hook and list required modules here instead:
MODULES="piix ide_disk reiserfs" [...] HOOKS="base autodetect ide filesystems"
Known modules that are not autoloaded during boot process (status stock kernel 2.6.18):
scsi_transport_sas, ultrastor, qlogicfas, eata, BusLogic, pas16, wd7000, sym53c416, g_NCR5380_mmio, fdomain, u14-34f, dtc initio, in2000, imm, t128, aha1542, aha152x, atp870u, g_NCR5380, NCR53c406a, qlogicfas408, megaraid_mm, advansys
If one of the above modules are required for the root device, consider explicitly adding it to Template:Filename to avoid kernel panics.
BINARIES and FILES
These options allow users to add files to the image; the difference being that BINARIES checks binaries and libraries for dependencies, while FILES simply adds the file without checks. For example:
Customizing the kernel command line
Just like without initramfs, some options need to be passed on the kernel command line to configure your kernel, like the root device. Some of the mkinitcpio hooks have special options. These are discussed below.
Entering failsafe mode
If you add the option
to the kernel command line, init stops after the setup is completed and you are left with a dash shell. This can be used to verify that everything went fine. If you logout, normal boot continues.
You can disable a hook at runtime by adding the disablehooks option to the kernel command line like this:
You can blacklist modules by adding the disablemodules option to the kernel command line like this:
First add the 'mdadm' hook to the HOOKS list and any required raid modules to the MODULES list 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 arrays during the init phase of boot.
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:
ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> nfsaddrs= is an alias to ip= and can be used too.
<client-ip> IP address of the client. If empty, the address will either be determined by RARP/BOOTP/DHCP. What protocol is used de- pends 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 request. <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 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.
ip=127.0.0.1:::::lo:none --> Enable the loopback interface. ip=192.168.1.1:::::eth2:none --> Enable static eth2 interface. ip=:::::eth0:dhcp --> Enable dhcp protocol for eth0 configuration.
If the 'nfsroot' parameter is NOT given on the command line, the default "/tftpboot/%s" will be used.
<server-ip> Specifies the IP address of the NFS server. If this field is not given, the default address as determined by the `ip' variable (see below) is used. One use of this parameter is for example to allow using different servers for RARP and NFS. Usually you can leave this blank. <root-dir> Name of the directory on the server to mount as root. If there is a "%s" token in the string, the token will be replaced by the ASCII-representation of the client's IP address. <nfs-options> Standard NFS options. All options are separated by commas. If the options field is not given, the following defaults will be used: port = as given by server portmap daemon rsize = 1024 wsize = 1024 timeo = 7 retrans = 3 acregmin = 3 acregmax = 60 acdirmin = 30 acdirmax = 60 flags = hard, nointr, noposix, cto, ac
If you don't use nfsroot= parameter you need to set root=/dev/nfs to boot from a nfs root by autoconfiguration.
If your root device is on lvm, you have to add the lvm2 hook. You have to pass your root device on the kernel command line in the format
root=/dev/mapper/<volume group name>-<logical volume name>
Using encrypted root
If your root volume is encrypted, you need to add the encrypt hook. Then specify your root device on the kernel command line, just as if it was unencrypted.
For an encrypted partition on an sata or scsi disk:
For an encrypted lvm volume:
The root device will be automatically changed to /dev/mapper/root.
Using LUKS volumes
If you use LUKS for hard disk encryption, the init script will detect the encryption automatically if the encrypt hook is enabled. It will then ask for a passphrase and try to unlock the volume.
If this fails try to add you filesystem-module to the module list in /etc/mkinitcpio.conf if it's not compiled into your kernel.
Using a key-file
You can use a keyfile to encrypt your root-fs. Use the following format:
Device is the device-file representing the device your key is stored on (e.g. /dev/sda1), fs-type is the filesystemtype of this device (e.g. ext3) and path is the path to the keyfile inside the fs of this device.
Using legacy cryptsetup volumes
If you are using a legacy cryptsetup volume, you have to specify all cryptsetup options necessary to unlock it on the kernel command line. The option format is
representing cryptsetup's --hash, --cipher, --keysize, --offset and --skip options. If you omit an option, cryptsetup's default value is used, so you can just specify
if you created your volume with the default settings.
NOTE: For technical reasons, it is not possible to verify the correctness of your passphrase with legacy cryptsetup volumes. If you typed it wrong, mounting will simply fail. It is recommended that you use LUKS instead.
Using loop-aes volumes
mkinitcpio does not support loop-aes yet.
Add a Delay
if you need to wait for a few seconds before mounting /. For example if you have a usb hard drive that takes a while to become ready. The example below will pause 8 seconds before continuing.
Example bootloader configuration files
If you use the beyond kernel, the filenames are kernel26beyond.img and kernel26beyond-fallback.img instead of kernel26.img and kernel26-fallback.img, respectively. Also, change "vmlinuz26" to "vmlinuz26beyond".
For those who have /boot on a separate partition:
# (0) Arch Linux title Arch Linux root (hd0,3) kernel /vmlinuz26 root=/dev/hda4 vga=791 ro initrd /kernel26.img title Arch Linux Fallback root (hd0,3) kernel /vmlinuz26 root=/dev/hda4 vga=791 ro initrd /kernel26-fallback.img
For those who do _not_ have /boot on a separate partition:
# (0) Arch Linux title Arch Linux root (hd0,3) kernel /boot/vmlinuz26 root=/dev/hda4 vga=791 ro initrd /boot/kernel26.img title Arch Linux Fallback root (hd0,3) kernel /boot/vmlinuz26 root=/dev/hda4 vga=791 ro initrd /boot/kernel26-fallback.img
If you use LILO, it is recommended that you use append="root=/dev/XYZ" instead of root=/dev/XYZ. If you already have a global append option, then use addappend.
boot=/dev/hdX default = ArchLinux timeout=50 vga=791 lba32 prompt # for the hardware-autodetecting image image=/boot/vmlinuz26 label=ArchLinux append="root=/dev/hdXY" initrd=/boot/kernel26.img read-only # fallback image if the other doesnt work (Will most prob. never be used) image=/boot/vmlinuz26 label=ArchLinuxFallBack append="root=/dev/hdXY" initrd=/boot/kernel26-fallback.img read-only
mkinitcpio hangs on 'autodetect' during kernel upgrade
This bug sometimes causes mkinitcpio to hang when upgrading the kernel. It has been noted that certain usb devices and pata hard drives/chipsets may irritate the issue, but the actual cause is currently unknown (2010-03-01). The best known method to circumvent this bug is to edit '/etc/mkinitcpio.conf' and remove 'autodetect' from the HOOKS parameter. Once removed, force reinstall the kernel with 'pacman -Sf kernel26', and mkinitcpio should process cleanly.
Reboot the system, and then add 'autodetect' back to the HOOKS parameter, and force reinstall the kernel again to complete this workaround. While running on the new kernel, 'autodetect' seems to process successfully.
NOTE: Be very careful modifying 'etc/mkinitcpio.conf'. Review the procedures BEFORE modifying, and make a backup. Some systems may need another hook for pata/ide, or sata if the respective hook is not yet present. If mkinitcpio fails during a kernel upgrade, and the issue is not resolved before a reboot is executed, this will most likely result in a kernel panic/nonfunctioning system!
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 a cpio archive, generated by the gen_init_cpio command, optionally compressed with one the 3 compression schemes understood by the kernel: namely gzip or bzip2 or lzma. Only kernels later than 2.6.30 undertand bzip2 and lzma compression.
bsdtar is powerful enough to autodetect the compression used and to extract to the current directory.
You can list the files in the image with:
$ bsdtar -t -f /boot/kernel26.img
And to extract them all in the current directory:
$ bsdtar -x -f /boot/kernel26.img