Configuring mkinitcpio
From ArchWiki
Article summary |
---|
mkinitcpio configuration manual |
Available in languages |
English |
Русский |
Related articles |
About
mkinitcpio is the next generation of initramfs creation. It has many advantages above the old mkinitrd and mkinitramfs scripts.
- It uses klibc and kinit which are developed by Linux kernel devs to provide a small and lightweight base for early userspace.
- It can use udev for hardware autodetection at runtime, thus prevents you from having tons of unnecessary modules loaded.
- Its hook-based init script is easily extendable with custom hooks, which can easily be included in pacman packages without having to modifiy mkinitcpio itself.
- It already supports lvm2, dm-crypt for both legacy and luks volumes, raid, mdadm, swsusp and suspend2 resuming and booting from usb mass storage devices.
- Many features can be configured from the kernel command line without having to rebuild the image.
- The mkinitcpio script makes it possible to include the image in a kernel, thus making a self-contained kernel image is possible.
mkinitcpio has been developed by phrakture and tpowa with some help from the community.
Installing mkinitcpio
From the [core] repository
The mkinitcpio script can be found in the [core] repository. You can install with the command
# pacman -S mkinitcpio
From Git
If you want the latest development version of mkinitcpio, check out its Git tree using
# git clone git://projects.archlinux.org/mkinitcpio.git
Activation for >=2.6.17 kernels
There will be 2 images created during kernel installation/upgrade:
If you are using kernel26
/boot/kernel26.img --> stripped down in size by autodetect /boot/kernel26-fallback.img --> contains all modules of subsystems
If you are using kernel26beyond
/boot/kernel26beyond.img --> stripped down in size by autodetect /boot/kernel26beyond-fallback.img --> contains all modules of subsystems
Please change your bootloader to load the image you need.
ATTENTION:
=> lvm2, raid, mdadm and encrypt are NOT enabled by default
lvm2, raid and encrypt are not enabled by default. Please read this wiki carefully on how to set those up for your system.
=> Users with more than 1 hardware disk controller
If you have more than one hardware disk controller which uses the same node names (like 2 SCSI/SATA or IDE controllers) and need different kernel modules to load them, please specify the correct order in MODULES="" in /etc/mkinitcpio.conf and in your fallback config file, else it could happen that your root device keeps on switching and you could run into random kernel panics.
A more elegant alternative is to use Persistent block device naming to ensure that the right devices are mounted.
Known modules that are not autoloaded during boot process
If you need one of the following modules for your root device, consider to load them by MODULES="" in /etc/mkinitcpio.conf and in your fallback config file, else your kernel panics during boot.
- SCSI CONTROLLERS (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
Customizing the Configuration Files
Modifying main image
To change the defaults for the main image edit the following file:
/etc/mkinitcpio.conf
mkinitcpio uses this file by default.
Modifying fallback image
To change the defaults for the fallback images, edit one of the following files:
if you use kernel26, edit /etc/mkinitcpio.d/kernel26-fallback.conf if you use kernel26beyond, edit /etc/mkinitcpio.d/kernel26beyond-fallback.conf
and set the file that you edited to NoUpgrade = in '/etc/pacman.conf'. Note that these should be sane unless you require a special setup such as lvm or raid.
Configuring the HOOKS
This is the most important part of mkinitcpio configuration. The HOOKS line contains the hooks that are executed on image creation and on runtime in the exact order they are listed. The format is like this:
HOOKS="foo1 foo2 foo3 bar1 bar2"
Available hooks
Hook | Installation | Runtime |
---|---|---|
base | Sets up all initial directories and installs base klibc 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. |
modload | An alternative autodetection method which is much slower than udev. Using this hook is discouraged. Use udev instead. | |
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 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 or modload hook unless you specify the needed modules manually (see MODULES section below). |
pata | Adds 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 or modload hook unless you specify the needed modules manually (see MODULES section below). PATA is the kernel's new IDE driver. It will change your /dev/hd? to /dev/sd?. more info: http://archlinux.org/news/272/ |
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 or modload 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 or modload 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 or modload 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 or modload 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 or modload 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 pcmcia hook too. | Loads network modules. You will need the udev or modload hook unless you specify the needed modules manually (see MODULES section below). See the section Customizing the kernel command line for further configuration. |
pcmcia | Adds the necessary modules for pcmcia devices. You need to have pcmciautils installed to use this. | Loads pcmcia modules. You will need the udev or modload 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 /lib/initcpio/custom.dsdt | 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 fs modules in MODULES. | This will detect the filesystem type at runtime, load the module and pass it to kinit. NOTE: it will NOT detect reiser4, it must be added to modules list. |
lvm2 | Adds the device mapper kernel module and the lvm tool to the image. You need to have the lvm2 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 mdassamble for a software raid setup. This hook has been superseded by the mdadm hook. You need to have mdadm installed to use this. | Loads the necessary modules for software raid devices, and assembles the raid devices when run. See the section Customizing the kernel command line for further configuration. |
mdadm | This hook supersedes the above raid hook. It supports assembling the arrays from /etc/mdadm.conf, or autodetection during boot | Loads the necessary modules for software raid devices, and assembles the raid devices when run. See the section Customizing the kernel command line for further configuration. |
encrypt | Adds the dm-crypt kernel module and the cryptsetup tool to the image. You need to have the cryptsetup package installed to use this. | Detects and unlocks an encrypted root partition. See the section Customizing the kernel command line for further configuration. |
resume | This tries to resume from "suspend to disk" state. Works with both swsusp and suspend2. See the section Customizing the kernel command line for further configuration. | |
firmware | Adds /lib/firmware 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 rc.conf during early userspace. |
Examples
This configuration will work for most users with a standard setup:
HOOKS="base udev autodetect ide scsi sata filesystems"
If you want to use the image on more than one machine, use this configuration:
HOOKS="base udev ide scsi sata filesystems"
You can use encrypted volumes on top of lvm2 volume groups:
HOOKS="base udev autodetect ide scsi sata lvm2 encrypt filesystems"
Configuring the MODULES
You can use the MODULES in the configuration file to load a module before anything else is done. For example, if you don't want to use udev or modload, you can add all necessary modules manually and make booting faster:
MODULES="piix ide_disk reiserfs" HOOKS="base autodetect ide filesystems"
NOTE: if you're using reiser4, you MUST add it to the modules list.
Configuring the BINARIES and FILES
These options allow you to add files to the image. The only difference is that BINARIES checks binaries and libraries for dependencies, while FILES simply adds the file.
Examples:
FILES="/etc/modprobe.conf"
BINARIES="/usr/bin/somefile"
Creating the image
Regenerating predefined images / using presets
If you want to regenerate the default preset initramfs image for the Arch Linux stock kernel, use the command:
# mkinitcpio -p kernel26
This example is for the kernel26 package, it works the same for the other kernel packages.
If you want to change the settings for preset images, edit the /etc/mkinitcpio.d/kernel26.preset file (again, just change the filename for the other kernel packages). These .preset files will be used on a kernel update, so don't break them.
Manually
Creating the image according to configurations specified in /etc/mkinitcpio.conf is achieved with the following command:
mkinitcpio -g /boot/kernel26.img
This will generate the initramfs image for the currently running kernel and save it at /boot/kernel26.img, which is also the location for the kernel26 package. Users of kernel26beyond should use the following instead:
mkinitcpio -g /boot/kernel26beyond.img
If you are creating an image for a kernel other than the one you are currently running, add the kernel version to the command line:
mkinitcpio -g /boot/kernel26.img -k 2.6.16-ARCH
Regenerating the Fallback Image
NOTE: The following may confuse some people. It is only intended to help create fallback images for people already running the current kernel. To create images for any kernel that is not currently running, you MUST use the -k parameter.
A fallback image should have been created when you installed kernel26 or kernel26beyond but in case you want to re-generate it
mkinitcpio -c /etc/mkinitcpio.d/kernel26-fallback.conf -g /boot/kernel26-fallback.img
for beyond
mkinitcpio -c /etc/mkinitcpio.d/kernel26beyond-fallback.conf -g /boot/kernel26beyond-fallback.img
See mkinitcpio -h for more options.
Don't forget to add a new bootloader entry. Just make a copy of your old one and change the initrd to your new image. As long as mkinitcpio is beta, please always leave the old one intact, so that you can boot it if something goes wrong. You can use mkinitcpio with any kernel, so kernel26 and kernel26-beyond users are encouraged to try it.
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.
If you don't know what a kernel command line is, please refer to the GRUB or Lilo documentation.
Entering failsafe mode
If you add the option
break=y
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.
Disabling hooks
You can disable a hook at runtime by adding the disablehooks option to the kernel command line like this:
disablehooks=hook1,hook2,hook2
for example
disablehooks=resume
Blacklisting modules
You can blacklist modules by adding the disablemodules option to the kernel command line like this:
disablemodules=mod1,mod2,mod3
for example
disablemodules=ata_piix
Using raid
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.
Using net
Kernel Parameters:
ip=
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.
Parameter explanation:
<client-ip> IP address of the client. If empty, the address will either be determined by RARP/BOOTP/DHCP. What protocol is used 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.
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.
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 don't use nfsroot= parameter you need to set root=/dev/nfs to boot from a nfs root by autoconfiguration.
Using lvm
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>
for example
root=/dev/mapper/myvg-root
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:
root=/dev/sda5
For an encrypted lvm volume:
root=/dev/mapper/myvg-root
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:
cryptkey=device:fs-type:path
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
crypto=hash:cipher:keysize:offset:skip
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
crypto=::::
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.
rootdelay=8
Using Suspend to Disk
If you want to use suspend to disk, you have to add the resume hook.
swsusp
TODO
µswsusp
µswsusp is not supported yet. However, there is a working package 'uswsusp' in AUR. You need to add the uresume hook to your HOOKS-array (just before filesystems). (This is also said in the post-install message of 'uswsusp'.)
suspend2
NOTE since mkinitcpio 0.5.18-1 for tuxonice (the new name of suspend2) you should use the resume= parameter too
If you are using suspend2, you have to specify the resume2 kernel commandline option. If you are using the swap writer, use
resume2=swap:/dev/hda3
where /dev/hda3 is your swap partition. If you want to use the filewriter, use
resume2=file:/dev/hda2:0x123456
where /dev/hda2 is the partition where the suspend2 image is stored (most likely the root partition) and 0x123456 is the file offset. You can get the exact value with the commands
echo "/suspend2_file" > /proc/suspend2/filewriter_target cat /proc/suspend2/resume2
where /suspend2_file is the path to your suspend image file. This - of course - works for lvm volumes as well. You can also use a suspend file on an encrypted root partition with the option
resume2=file:/dev/mapper/root:0x123456
where 0x123456 is the offset again. Resuming from an encrypted swap partition is not supported.
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".
GRUB
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
LILO
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
Troubleshooting
piix ide controllers and beyond kernel
Problem
If you are having problems getting mkinitcpio to detect your hard drive giving errors akin to "Can't find device dev(0,0)" when switching to kinit, then this could be because of a conflict that the ata_piix and piix drivers have. The beyond kernel has some libata patches that cause ata_piix to *conflict* with piix.
Solution
Edit /etc/mkinitcpio.conf to only have ide or sata or scsi depending on what your system actually needs to boot.
Getting under the hood
If you are curious about what is inside the initrd image you can extract it and poke at the files inside of it.
File format
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 latter than 2.6.30 undertand bzip2 and lzma compression.
Using bsdtar to extract the image
bsdtar is powerfull enough to autodetect the compression used and to extract to the current directory.
You can view the list of 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