Mkinitcpio

Einleitung

mkinitcpio ist die nächste Generation der initramfs-Erstellung. Es hat viele Vorteile gegenüber der alten mkinitrd und mkinitramfs Scripte.

• Es nutzt klibc und kinit der Linux-Entwicklern welches eine kleine und leichtgewichtige Basis bereitstellt, um Programme sehr früh im userspace laufen zu lassen.
• Es kann mittels udev die Hardware zur Laufzeit erkennen, so daß nur die wirklich nötigen Module geladen werden.
• Die hook-basierenden init Scripte sind leicht erweiterbar und können auch durch externe Pakete genutzt werden.
• Es unterstützt bereits lvm2, dm-crypt (legacy und luks volumes), raid, swsusp und suspend2 Fortsetzen und Starten vob usb Datenträgern.
• Viele Funktionen können von der Kernel-Kommandozeile konfiguriert werden ohne das Image neu erstellen zu müssen.
• Mit dem mkinitcpio Skript ist es möglich, das Image in den Kernel zu integrieren.

mkinitcpio wurde von phrakture und tpowa mit einiger Hilfe von der Community entwickelt.

Installation von mkinitcpio

Aus dem current Repository

Das mkinitcpio Script ist im current Repository verfügbar. Du kannst es mit pacman installieren:

# pacman -Sy mkinitcpio

Aus dem svn

Die aktuelle Entwickler-Version von mkinitcpio kannst Du aus phraktures svn Repository laden:

# svn co http://phraktured.net/initramfs

Die neuesten Scripte befinden sich nun im initramfs/mkinitcpio Verzeichnis.

Aktivierung für Kernel ab 2.6.17

Es werden zwei Images während der Installation des Kernels erstellt:

- kernel26

/boot/kernel26.img --> enhält nur die automatisch erkannten Module
/boot/kernel26-fallback.img --> enthält alle Module

- kernel26beyond

/boot/kernel26beyond.img --> enhält nur die automatisch erkannten Module
/boot/kernel26beyond-fallback.img --> enthält alle Module

Ändere Deine Bootloader-Konfiguration Deinen Bedürfnissen entsprechend.

Achtung => lvm2, raid and encrypt werden standardmäßig nicht aktiviert!

Zur Konfiguration dieser System lese bitte die entsprechenden Anleitungen im Wiki.

Anpassung der Konfigurations-Dateien

Änderung es Haupt-Image

Um die Standard-Einstellungen des Haupt-Image zu ändern, nutze folgende Datei:

/etc/mkinitcpio.conf

mkinitcpio benutzt standardmäßig diese Datei.

Änderung des Fallback-Image

Um die Standard-Einstellungen des Fallback-Image zu ändern, nutze folgende Dateien:

kernel26 --> '/boot/mkinitcpio-kernel26.conf'
kernel26beyond --> '/boot/mkinitcpio-kernel26beyond.conf

und füge die Dateien der Zeile NoUpgrade = der '/etc/pacman.conf' hinzu. Dies ist nur bei speziellen Konfigurationen mit lvm oder raid nötig.

Konfiguration der HOOKS

Dies ist der wichtigste Teil der mkinitcpio Konfiguration. Die HOOKS Zeile enthält alle hooks die während der Abbild-Erstellung oder zur Laufzeit ausgeführt werden. Hierbei wird die Reihenfolge beachtet:

HOOKS="foo1 foo2 foo3 bar1 bar2"

Verfügbare hooks

Hook	Installation	Laufzeit
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 autodetecion 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).
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.	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 necessary if you want to be able to boot	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. 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.
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.

Beispiele

Diese Konfiguration sollte für die meisten Benutzer funktionieren:

HOOKS="base udev autodetect ide scsi sata filesystems"

Möchtest Du das Abbild auf mehr als einer Maschine nutzen, so benutze folgende Konfiguration:

HOOKS="base udev ide scsi sata filesystems"

Du kannst verschlüsselte Dateisystem innerhalb von lvm nutzen:

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

Create the image with the following command:

mkinitcpio -g /boot/kernel26.img

This will generate the image for the currently running kernel and save it at /boot/kernel26.img, which is the location for 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

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 /boot/mkinitcpio-kernel26.conf -g /boot/kernel26.img

for beyond

mkinitcpio -c /boot/mkinitcpio-kernel26beyond.conf -g /boot/kernel26beyond.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

THIS FEATURE IS AVAILABLE SINCE MKINITCPIO 0.5.1

Using raid

First add the raid hook to the HOOKS list in /etc/mkinitcpio.conf

Kernel Parameters: Specify all your md arrays with md= parameter: (only adding the raid array you're booting from is enough)

add the following to the kernel line in grub/menu.lst:

 Example: md=0,/dev/sda3,/dev/sda4 md=1,/dev/hda1,/dev/hdb1
 working example: kernel /vmlinuz26beyond root=/dev/md0 ro md=0,/dev/sda1,/dev/sdb1

This will setup 2 md arrays with persistent superblocks

Setup:

 - for old raid arrays without persistent superblocks:
   md=<md device no.>,<raid level>,<chunk size factor>,<fault level>,dev0,dev1
 - for raid arrays with persistent superblocks:
   md=<md device no.>,dev0,dev1,...,devn
 - for, to assemble a partitionable array:
   md=d<md device no.>,dev0,dev1,...,devn

Parameters:

 - <md device no.> = the number of the md device: 
   0 means md0, 1 means md1, ...
 - <raid level> = -1 linear mode, 0 striped mode
   other modes are only supported with persistent super block
 - <chunk size factor> = (raid-0 and raid-1 only):
   Set  the chunk size as 4k << n.
 - <fault level> = totally ignored
 - <dev0-devn>: e.g. /dev/hda1,/dev/hdc1,/dev/sda1,/dev/sdb1

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

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 example

root=/dev/sda5

for an encrypted partition on an sata or scsi disk or

root=/dev/mapper/myvg-root

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.

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.

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.

suspend2

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 = <Label of default image>
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.