Important: You are required to change your passwords used for Gentoo services and set an email address for your Wiki account if you haven't done so. See the full announcement and Wiki email policy change for more information.

Dracut

From Gentoo Wiki
Jump to: navigation, search

Dracut is an initramfs infrastructure and aims to have as little as possible hard-coded into the initramfs. It originated from the Fedora Project and was ported to Gentoo in the 2010 Google Summer of Code. For more detailed information, refer to the documentation at kernel.org.

Installation

Before you can use the images generated by dracut, your kernel must include initramfs support. The ebuild will warn you if your kernel is missing the required options:

Kernel configurationEnabling the initramfs

    General setup  --->
        [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
    Device Drivers --->
        Generic Driver Options --->
            [*] Maintain a devtmpfs filesystem to mount at /dev   

The behavior of dracut is controlled by dracut modules (not to be confused with kernel modules). Each dracut module you include in your initramfs produces certain additional behavior at boot time. By default, sys-kernel/dracut installs a set of base modules that are most commonly needed for systems where the rootfs is found on a simple local block device. If you need additional features, such as RAID, LVM, or NFS mounted root support, you can install optional modules by listing them in the DRACUT_MODULES expansion variable in /etc/portage/make.conf:

File/etc/portage/make.conf

DRACUT_MODULES="gensplash nfs"

Certain modules also require additional USE flags to be set (see Optional Modules for details). In general, you should not enable any of the USE flags for sys-kernel/dracut unless Portage asks you to. It will tell you if there are any missing REQUIRED_USE constraints when you attempt to merge:

root # DRACUT_MODULES=lvm emerge --ask dracut
  The following REQUIRED_USE flag constraints are unsatisfied:
    dracut_modules_lvm? ( device-mapper ) dracut_modules_nfs? ( net )

Since sys-kernel/dracut is still unstable, if you are not already running ~arch, you will need to keyword it:

root # echo "sys-kernel/dracut" >> /etc/portage/package.keywords
root #
emerge --ask sys-kernel/dracut

Building An initramfs Image

Default Images

Once you have installed dracut, you can use it to build an initramfs image. The simplest way to do this is to just run

root # mount /boot
root #
dracut

The initramfs image created this way is a generic image, which will include all installed modules and system tools that it can find, suitable for booting a variety of machines. If you are producing an initramfs for just a single machine, you can specify that dracut should go into host-only mode:

root # dracut --hostonly

The produced image will contain only those elements used by the local machine for booting. Certain modules behave differently in host-only mode. The kernel-modules module, for example, will only include the tools and modules used by the current rootfs file system, and the i18n module will install the fonts and keymaps for the local machine. Otherwise, every available file system, font, etc. would be included.

By default, dracut will produce an image suitable for booting the currently active kernel; it will pull the kernel modules needed for that kernel, etc. The output will be written into your /boot folder (which you should already have mounted), in a file called /boot/initramfs-<kernel version>.img. You can override both options by specifying a new file name and kernel version on the command line, in that order. Both parameters are optional, but if you want to override the kernel version and keep the default file name you need to pass a placeholder empty string as the first parameter:

root # dracut --hostonly '' 3.2.5-hardened

Default Modules

When installed without any use flags, dracut installs a basic set of modules that can boot a system using a locally attached block device for its rootfs. The purpose of each module is to arrange for files to be included in the final initramfs image. In addition, dracut exposes hooks that run at certain points, which modules can hook into to perform required boot actions.

Module Description Enabled?
dash includes /bin/dash as /bin/sh always
i18n includes keymaps, console fonts, etc. always
rpmversion includes dracut version in initramfs when /etc/redhat-release exists
convertfs merges / into /usr on next boot never
kernel-modules includes the kernel modules for root filesystems and other boot-time devices always
fstab-sys arranges for arbitrary partitions to be mounted before rootfs when /etc/fstab.sys exists, or command line includes --fstab or --add_fstab
resume allows initramfs to resume from low-power state when swap partition exists
rootfs-block arranges for the block device containing the rootfs to be mounted always
terminfo includes a terminfo file always
udev-rules includes udev and some basic rules always
securityfs arranges for the securityfs to be mounted early never
usrmount arranges for /usr to be mounted always
base includes most basic utilities always
fs-lib includes filesystem tools (including mount) always
img-lib includes tools to decompress images never
shutdown sets up hooks to run on shutdown always
  • The Enabled field indicates when a particular module will be included by default into your initramfs image.
  • Modules with pre-requisite packages cannot be included (even explicitly) if the required software is missing from the host.

Adding Modules

The table above indicates when a particular module will be included in your initramfs image by default. You can override this module list in two ways: command line, or configuration file. Editing your configuration file will set up dracut to be re-run easily when you change kernels or other boot-time options. Options specified in /etc/dracut.conf can be overridden by files in /etc/dracut.conf.d, which are installed by various dracut-aware packages. Both options can be overridden by command-line parameters. The following configuration options deal with the default modules list:

File/etc/dracut.conf

# Equivalent to -H
hostonly="yes"

# Equivalent to -m "module module module"
dracutmodules+="dash kernel-modules rootfs-block udev-rules usrmount base fs-lib shutdown"

# Equivalent to -a "module"
add_dracutmodules+="module"

# Equivalent to -o "module"
omit_dracutmodules+="module"

Specifying dracutmodules (or the -m parameter) will override the entire default list, and install only those modules you specified. This can help cut down significantly on your image size (for example, if you don't need any kernel modules, or i18n support, etc.) If you aren't sure which modules you need, you should build one fully-featured image and keep it in /boot while you experiment. If anything goes wrong, you can edit your grub.conf at boot to switch to that.

The other options can be used to add or remove items from the default list, including your own custom modules. If a module refuses to install (for example, its prerequisite binaries are mossing) there is a --force-add command-line switch (but no matching configuration option) to add them anyway. Note that forcing a module to be added this way is dangerous, as the installed scripts will likely to run execute commands that are not present.

Optional Modules

Adding additional modules to your installation involves setting the appropriate values for your DRACUT_MODULES variable, as described in the Installation section. Each additional module you include brings with it additional prerequisite packages, and may require USE flag changes to either sys-kernel/dracut or other modules. In most cases, you should already have the additional packages installed. If dracut tries to bring in a lot of additional packages you should confirm that you are asking for the correct module.

The optional modules included as of sys-kernel/dracut-016 are listed below, with their additional requirements.

Module Purpose Enabled? USE Flag Additional Packages
biosdevname enables BIOS network device renaming always sys-apps/biosdevname, sys-apps/pciutils
btrfs supports a btrfs rootfs host-only: rootfs sys-fs/btrfs-progs
caps supports dropping capabilities before init always sys-libs/libcap (also replaces dash with bash)
crypt supports an encrypted rootfs host-only: rootfs device-mapper, static-libs4 sys-fs/cryptsetup
crypt-gpg use gpg for crypt support (requires crypt module) never app-crypt/gnupg
dmraid support rootfs on FakeRAID host-only: rootfs device-mapper sys-fs/multipath-tools, sys-fs/dmraid
dmsquash-live supports LiveCD rootfs never (host-only: refused) device-mapper
gensplash include a static splash screen never static-libs4 media-gfx/splashutils
iscsi supports rootfs on iscsi devices host-only: rootfs net sys-block/open-iscsi
livenet retrieve rootfs over HTTP (requires dmsquash-live modules) never device-mapper, net
lvm supports rootfs on LVM device host-only: rootfs device-mapper sys-fs/lvm2
mdraid supports rootfs on software RAID host-only: rootfs sys-fs/mdadm
multipath supports rootfs on multi-path device host-only: rootfs sys-fs/multipath-tools
nbd supports rootfs on a network block device host-only: rootfs net sys-block/nbd
nfs supports NFS-mounted rootfs net host-only: rootfs net-fs/nfs-utils net-nds/rpcbind
plymouth includes boot animation always libkms3 sys-boot/plymouth
ssh-client includes ssh and scp clients never net dev-libs/openssl
syslog includes remote logging support never app-admin/syslog-ng or rsyslog
debug includes useful troubleshooting tools never installed when USE=debug
dm includes device-mapper never installed when USE=device-mapper sys-fs/device-mapper or sys-fs/lvm2
ifcfg generates network config at runtime never installed when USE=net
network brings up network for net booting always installed when USE=net net-misc/dhcp, sys-apps/iproute2
selinux arranges for the selinux policy to be loaded never installed when USE=selinux
url-lib includes cUrl and SSL certs never installed when USE=net net-misc/curl
  1. sys-boot/plymouth requires that x11-libs/libdrm be built with the libkms flag
  2. The additional packages require that one or more dependency libraries be built with the static-libs flag
  3. The Enabled field specifies when an installed module will be included by default into a built image:
    • Modules enabled for "host-only: rootfs" are included in host-only images if the active rootfs requires that module, and included in general-purpose images "always".
    • Modules enabled "never" must be explicitly added via the command-line or configuration file, as above.
    • Modules with pre-requisite packages cannot be included, even explicitly, if the required software is missing from the dracut build host.
    • dmsquash-live (and, by extension, livenet) cannot be installed in host-only mode, as that would be silly.

Customizing the Image

Besides defining the list of modules to include, you can also customize the final initramfs in a few other ways. The install_items option in the configuration file lets you specify an arbitrary number of arbitrary items to add to your image. Other options add specific elements to the image, as described below:

Kernel Modules

By default, the kernel-modules driver scans the list of available kernel modules, and installs the set of modules needed to boot a system and bring up the rootfs. This includes the hardware bus drivers (SCSI, ATA, USB, etc), keyboard drivers, block device drivers, and file system drivers. (In host-only mode, only the file systems used by the build host are included.) You can update the list of installed modules via the command-line or configuration file. When specifying a kernel module name, do not include the .ko extension.

File/etc/dracut.conf

# Equivalent to --drivers="module module module"
drivers+="module module module"

# Equivalent to --add-drivers
add_drivers+="module"

# Equivalent to --omit-drivers="module"
omit_drivers+="module"

# Equivalent to --filesystems="fs fs fs"
filesystems+="fs fs fs"

# Equivalent to --kmoddir="/lib/modules/fixed"
drivers_dir="/lib/modules/fixed"

# Equivalent to  --fwdir=":/lib/fw/alt:/lib/fw/alt2"
fw_dir+=":/lib/fw/alt:/lib/fw/alt2"
  • In host-only mode, the running hosts filesystems are always installed, regardless of the filesystems parameter.

Filesystems And Mount Points

The default image will arrange for your rootfs and your /usr partition (if different) to be mounted at boot time. The build process will obtain the device and file system information it needs from /proc/self/mountinfo. This may not be what you want, or you may need to have other partitions mounted as well. You can alter the behavior of the initramfs with the fstab-sys module, and the following options:

  • Create a file called /etc/fstab.sys, which will be copied to the initramfs and mounted.
  • Specify use_fstab="yes" (or --use-fstab), which will use your system's /etc/fstab instead of /proc/self/mountinfo
  • Specify add_fstab+="filename" or --add_fstab filename, which will add the contents of filename to the initramfs's /etc/fstab.
  • Specify --mount "fstab mount spec", which adds individual entries into your initramfs's /etc/fstab.

(Note that add_fstab does not automatically trigger fstab-sys to be included in the image; this may be a bug, as use_fstab does include the module but does not actually supply an /etc/fstab.)

Booting The initramfs

Any parameters you need to pass to the dracut modules are passed on the kernel command line. If you are net booting, the DHCP server can also provide command-line parameters. The dracut scripts parse the kernel command line very early in the boot process and use the information found there to adjust their behavior. The list of options, by module, can be found in the man dracut.cmdline page.

Tasks

ext Boot

For booting an ext(2,3,4) filesystem you don't need any of the optional dracut modules.

root # dracut -m "rootfs-block base" initramfs.img

Once you have the image built, the final step is to include the image in the boot loader. To do this, simply add a line in your grub.conf:

File/boot/grub/grub.conf

kernel /boot/vmlinuz root=UUID=00000000-0000-0000-0000-000000000000
initrd /boot/initramfs.img

It is recommended that you use the UUID= (or LABEL=) form of the root specification; to guard against your device names changing between boots. You can find the UUID of your root device by running this command:

root # ls -alF /dev/disk/by-uuid

NFS Boot

For an NFS boot, you need only 3 modules and the nfs dracut module.

→ Information about USE flags
USE flag Default Recommended Description
net No Yes Set of helper modules providing networking support.
dracut_modules_nfs No Yes Support NFS.
root # dracut -m "nfs network base" initramfs-nfs-only.img


Booting is done with the following line in your PXE config. The rd.ip=auto let's it auto detect the NFS settings through DHCP. The NFS boot path is provided to the client through the DHCP option "root-path" with the following value: <SERVER>:<NFS Export>

File/var/lib/tftpboot/pxelinux.cfg/default

...
 APPEND initrd=initramfs-nfs-only.img rd.ip=auto root=dhcp
...

NBD Boot

For an NBD boot, you need only 3 modules and the nbd dracut module.

→ Information about USE flags
USE flag Default Recommended Description
net No Yes Set of helper modules providing networking support.
dracut_modules_nbd No Yes Support NBD.
root # dracut -m "nbd network base" initramfs-nbd-only.img


Booting is done with the following line in your PXE config. The rd.ip=auto let's it auto detect the NBD settings through DHCP. The NBD boot path is provided to the client through the DHCP option "root-path" with the following value: nbd:<SERVER>:<NBD_PORT>:<FS>

Note
Connecting to name based exports is not documented. A code review of the module shows that specifying an export name instead of a port number is allowed and can be used to connect to name based exports.
File/var/lib/tftpboot/pxelinux.cfg/default

...
 APPEND initrd=initramfs-nbd-only.img rd.ip=auto root=dhcp
...

It is also possible to boot from a partititioned nbd device. To do this, the PXE config needs to include

  • a kernel parameter "nbd.max_part=X" with X>0 to load the nbd module with partition support
  • a root device setting specifying the partition to mount
  • a netroot setting as described above for the root-path.
File/var/lib/tftpboot/pxelinux.cfg/default

...
 APPEND initrd=initramfs-nbd-only.img rd.ip=auto nbd.max_part=X root=/dev/nbd0pY netroot=nbd:<SERVER>:<NBD_PORT|EXPORTNAME>
...
Note
During shutdown, networking (including dhcp) and nbd-client must not be stopped, otherwise the nbd can not be unmounted cleanly. For OpenRC, this can be configured in /etc/conf.d/net for DHCP client daemon options and /etc/conf.d/killprocs to exclude nbd-client processes from being killed.

Debug

For debugging the Dracut boot process, a special module is required. Including the module in the initramfs also includes several useful tools like scp for copying logfiles.

→ Information about USE flags
USE flag Default Recommended Description
debug No Yes Module installing additional tools like strace, file editor, ssh and more.
root # dracut -m "<other modules>" initramfs-with-debug-only.img


Using the rd.debug flag, all Dracut commands are shown. When you are dropped to the Dracut shell, the logfile will be available in /run/initramfs/init.log.

File/var/lib/tftpboot/pxelinux.cfg/default

...
 APPEND initrd=initramfs-with-debug.img rd.debug
...

Other Filesystems

Other filesystems than the ones that are available through the Dracut modules can be installed using the filesystems parameter. To include kernel modules, the kernel-modules Dracut module also has to be included. This module is installed by default.

root # dracut -m "kernel-modules base" --filesystems "squashfs" initramfs-with-squashfs.img

Custom Modules

A Quick Dracut Module

See Rich0's Gentoo Blog for now.

40uvesafb

Load the uvesafb kernel module and add the sys-apps/v86d binary to the initramfs.

File/usr/lib/dracut/modules.d/40uvesafb/module-setup.sh

#!/bin/bash

check() {
    [[ -x /sbin/v86d && -f "$srcmods/kernel/drivers/video/uvesafb.ko" ]]
}

depends() {
    return 0
}

installkernel() {
   hostonly='' instmods uvesafb
}

install() {
    dracut_install /sbin/v86d
    inst_hook pre-trigger 9 "$moddir/uvesafb-pretrigger.sh"
}
File/usr/lib/dracut/modules.d/40uvesafb/uvesafb-pretrigger.sh

#!/bin/sh
if getargbool 1 rd.uvesafb -n rd_NO_UVESAFB; then
    [ ! -c /dev/fb0 -a -e /sbin/v86d ] && modprobe uvesafb
fi