Dracut
Dracut is an initramfs infrastructure and aims to have as little as possible hard-coded into the initramfs.
Dracut originated from the Fedora Project and was ported to Gentoo in the 2010 Google Summer of Code. For more detailed information, refer to the project documentation.
Installation
USE flags
USE flags for sys-kernel/dracut Generic initramfs generation tool
Note: some packages have the dracut USE flag.
Kernel
Before using the images generated by dracut, the Linux kernel must include initramfs support. The ebuild will provide a warning post-installation if the kernel is missing the required options:
General setup --->
[*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
Device Drivers --->
Generic Driver Options --->
[*] Maintain a devtmpfs filesystem to mount at /dev
Certain dracut modules also require additional dependencies to function. A list of optional dependencies is listed at the end of the installation. The DRACUT_MODULES variable in make.conf is no longer used.
Emerge
Install dracut:
root #emerge --ask sys-kernel/dracutBuilding an initramfs image
Automation
Installing an initramfs image generated with Dracut can be automated by enabling the dracut USE flag on sys-kernel/installkernel. This will generate a new initramfs image via /sbin/installkernel everytime a kernel is installed via make install or emerge --config <distribution kernel package>.
Default images
Once dracut is installed, it can be used to build an initramfs image. The simplest way to do this is to just run:
root #mount /bootroot #dracutThe 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 producing an initramfs for just a single machine, it may be specified that dracut should go into host-only mode:
root #dracut --hostonlyThe image produced will then 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.
Hostonly mode can be also set as the default in /etc/dracut.conf:
/etc/dracut.confhostonly="yes"
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 image will be written in a file called /boot/initramfs-<kernel version>.img. Both options may be overridden by specifying a new file name and kernel version on the command line, in that order. Both parameters are optional. To override the kernel version and keep the default file name, add the --kver option:
root #dracut --hostonly --kver 3.2.5-hardenedModules
Dracut installs all available modules, though some may need additional dependencies. 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.
Adding modules
Dracut comes with a suitable set of default modules (see below). This module list can be overridden in two ways: on the command line, or in the configuration file. Editing the configuration file will set up dracut to be re-run easily when changing kernels or after modifying 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:
/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 " # Note leading and trailing spaces
# Equivalent to -o "module"
omit_dracutmodules+=" module " # Note leading and trailing spaces
Specifying dracutmodules (or the -m option) will override the entire default list, and install only the modules specified. This can cut down significantly on image size (for example, if no kernel modules are needed, or i18n support, etc.). If it is not clear which modules are needed, build one fully-featured image and keep it in /boot to experiment. If anything goes wrong, grub.conf may be edited at boot to switch to that.
The other options can be used to add or remove items from the default list, including custom modules. If a module refuses to install (for example, its prerequisite binaries are missing) 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.
List of modules
Full list of supported modules can be obtained using the --list-modules parameter. An incomplete list of modules is below, with their additional requirements (in order how dracut includes them into initramfs). [1]
| Module | Description | Enabled? | Depends on modules | Requirements | |
|---|---|---|---|---|---|
| base | Base module with required utilities | always | udev-rules | ||
| biosdevname | Enables BIOS network device renaming. | always | sys-apps/biosdevname (biosdevname) | ||
| cifs | Adds CIFS filesystem support | always; hostonly: rootfs | network | net-fs/cifs-utils (mount.cifs) | |
| crypt | Adds support for encrypted with LUKS filesystems | always; hostonly: rootfs | dm rootfs-block | sys-fs/cryptsetup (cryptsetup) | |
| systemd-cryptsetup | Use systemd-cryptsetup to unlock a device for crypt |
when required | dm rootfs-block crypt systemd-ask-password | sys-apps/systemd | |
| dmraid | Adds support for DMRAID arrays | always; hostonly: rootfs | dm rootfs-block | sys-fs/dmraid (dmraid) | |
| fcoe | Adds support for Fibre Channel over Ethernet (FCoE) | always; hostonly: rootfs | ?? (dcbtool fipvlan lldpad ip readlink fcoemon fcoeadm tr) | ||
| fcoe-uefi | Adds support for Fibre Channel over Ethernet (FCoE) in EFI mode | always; hostonly: rootfs | fcoe uefi-lib bash | ?? (dcbtool fipvlan lldpad ip readlink) | |
| fs-lib | Includes filesystem tools (including fsck.* and mount) | always | |||
| fstab-sys | Arranges for arbitrary partitions to be mounted before rootfs. | always if /etc/fstab.sys exists, or command line includes --fstab or --add_fstab |
fs-lib | ||
| i18n | Includes keymaps, console fonts, etc. | always | sys-apps/kbd (setfont, loadkeys, kbd_mode) | ||
| kernel-modules-extra | Includes and loads extra out-of-tree kernel modules | always | |||
| lunmask | Masks LUN devices to select only ones which required to boot | always; hostonly: rootfs when type in /sys/module/scsi_mod/parameters/scan is "manual" | |||
| mdraid | Adds support for mdadm arrays | always; hostonly: rootfs | rootfs-block | sys-fs/mdadm (mdadm) | |
| memstrack | Includes memstrack for memory usage monitoring | always | systemd | ?? (pgrep pkill memstrack) | |
| multipath | Adds support for multipath devices | always; hostonly: rootfs | rootfs-block dm | sys-fs/multipath-tools (multipath) | |
| nbd | Adds support for network block device devices | always; hostonly: rootfs | network rootfs-block | sys-block/nbd (nbd-client) | |
| nvmf | Adds support for NVMe over Fabrics devices | always; hostonly: rootfs | bash rootfs-block network | sys-apps/nvme-cli (nvme) app-misc/jq (jq) | |
| qemu-net | Includes network kernel modules for QEMU environment | always; in hostonly when required | |||
| resume | Allows initramfs to resume from low-power state | always; hostonly: rootfs when local swap partition exists - always | |||
| rootfs-block | Arranges for the block device containing the rootfs to be mounted | always | base fs-lib | ||
| shutdown | Sets up hooks to run on shutdown | always | base | ||
| terminfo | Includes a terminfo file | always | |||
| udev-rules | Includes udev and some basic rules | always | virtual/udev (udevadm) | ||
| usrmount | Arranges for /usr to be mounted | always | |||
| virtiofs | Adds virtiofs filesystems support | always; hostonly: rootfs | |||
| iscsi | Adds support for iSCSI devices | always; hostonly: rootfs | sys-block/open-iscsi (iscsi-iname iscsiadm iscsid) | ||
| kernel-modules | Includes and loads kernel modules for root filesystems and other boot-time devices | always | |||
| lvm | Supports LVM devices | always; hostonly: rootfs | rootfs-block dm | sys-fs/lvm2 (lvm, needs USE=lvm enabled), sys-apps/grep (grep) | |
| nfs | Adds support for NFS | always; hostonly: rootfs | network | net-fs/nfs-utils (rpc.statd mount.nfs mount.nfs4 umount sed chmod chown) net-nds/rpcbind (rpcbind portmap) | |
| btrfs | Adds BTRFS support | always; hostonly: rootfs | udev-rules | sys-fs/btrfs-progs | |
| crypt-gpg | Adds support GPG for crypto operations and SmartCards (may requires GPG keys) | when required; always if file /etc/dracut.conf.d/crypt-public-key.gpg exists | crypt | app-crypt/gnupg (gpg) | |
| caps | Supports dropping capabilities before init | when required; not working if systemd in use | bash | sys-libs/libcap (capsh) | |
| watchdog | Includes watchdog devices management; works only if systemd not in use | when required | watchdog-modules | ||
| rngd | Starts random generator serive on early boot | when required | systemd | sys-apps/rng-tools (rngd) | |
| dbus | Virtual package for dbus-broker or dbus-daemon | when required | OR(dbus-broker dbus-daemon) | ||
| convertfs | Merges / into /usr on next boot | when required | base bash | ||
| connman | Includes net-misc/connman support | when required | dbus systemd bash | sys-apps/sed (sed), sys-apps/grep (grep), net-misc/connman (connmand, connmanctl, connmand-wait-online) | |
| network-manager | Includes net-misc/networkmanager support | when required | dbus bash | sys-apps/sed (sed), sys-apps/grep (grep) | |
| network | Virtual module for network service providers | when required | OR(connman network-manager network-legacy systemd-networkd) kernel-network-modules | ||
| ifcfg | Includes /etc/sysconfig/network-scripts/* network scripts for network autogeneration | when required; always if there /etc/sysconfig/network-scripts/ | network | ||
| url-lib | Includes curl and SSL certs. | when required | network | net-misc/curl (curl) | |
| plymouth | Includes boot splash support via plymouth | when required | drm | sys-boot/plymouth (plymouthd plymouth plymouth-set-default-theme) | |
| bluetooth | Includes bluetooth devices support | when required; hostonly: always if there bluetooth keyboard or pointing device | systemd dbus | net-wireless/bluez | |
| cms | Includes support for mounting z/VM CMS disks | when required | znet zfcp dasd dasd_mod bash | ||
| lvmmerge | Merges lvm snapshots | when required | lvm dracut-systemd systemd bash | sys-fs/lvm2 (lvm, needs USE=lvm enabled), sys-apps/coreutils (dd), sys-apps/util-linux (swapoff) | |
| lvmthinpool-monitor | Monitor LVM thinpool service | when required | lvm | sys-fs/lvm2 (lvm), sys-apps/coreutils (tr, sort), virtual/awk (awk) | |
| dmsquash-live-ntfs | Includes support for SquashFS images located in NTFS filesystems | when required | dmsquash-live | sys-fs/ntfs3g (ntfs-3g) | |
| dmsquash-live | Includes support for SquashFS images | when required; hostonly: never | dm rootfs-block img-lib bash | ||
| livenet | Fetch live updates for SquashFS images | when required | network url-lib dmsquash-live img-lib bash | ||
| crypt-loop | Adds support for encrypted loopback devices (symmetric key) | when required | crypt | sys-apps/util-linux losetup | |
| pcsc | Adds support for PCSC Smart cards | when required | systemd-udevd | sys-apps/pcsc-lite (pcsc) | |
| pkcs11 | Includes PKCS#11 libraries | when required | systemd-udevd | ||
| tpm2-tss | Adds support for TPM2 devices | when required | systemd-sysusers systemd-udevd | app-crypt/tpm2-tools (tpm2) | |
| ssh-client | Includes ssh and scp clients | when required | network | dev-libs/openssl (ssh scp) | |
| ecryptfs | Adds ecryptfs filesystems support | when required | masterkey | ||
| integrity | Adds support for Extended Verification Module | when required | masterkey securityfs | ||
| squash | Builds SquashFS initramfs | when required | systemd-initrd | ?? (mksquashfs unsquashfs) | |
| uefi-lib | Includes UEFI tools | when required | bash | ||
| bash | Includes /bin/bash as /bin/sh | when required; bash is preferred interpreter if there more of them available | app-shells/bash (bash) | ||
| dash | Includes /bin/dash as /bin/sh | when required | app-shells/dash (dash) | ||
| mksh | Includes /bin/mksh as /bin/sh | when required | sys-apps/coreutils (printf) app-shells/mksh (mksh) | ||
| systemd-network-management | Adds network management for systemd | when required | |||
| systemd | Adds systemd as early init initialization system | when required | sys-apps/systemd | ||
| warpclock | Sets kernel's timezone and reset the system time if adjtime is set to LOCAL | when required | sys-apps/util-linux (hwclock) | ||
| fips | Enforces FIPS security standard regulations | when required | |||
| modsign | Adds signing kernel modules support | when required; in hostonly mode requires keys from /lib/modules/keys/ | sys-apps/keyutils (keyctl) | ||
| rescue | Includes various utilities for rescue mode (such as ping, ssh, vi, fsck.*) | when required | |||
| watchdog-modules | Includes watchdog kernel modules to be loaded early in booting | when required | |||
| busybox | Includes /bin/busybox as replacement of utilities supported by busybox --list | when required | sys-apps/busybox (busybox) | ||
| dbus-broker | Use sys-apps/dbus-broker as dbus service provider | when required | sys-apps/dbus-broker (busctl, dbus-broker, dbus-broker-launch) | ||
| dbus-daemon | Use sys-apps/dbus as dbus service provider | when required; dbus-broker not in use | sys-apps/dbus (busctl, dbus-broker, dbus-broker-launch) | ||
| network-legacy | Includes legacy networking tools support | when required | sys-apps/iproute2 (ip), ? (dhclient), sys-apps/sed (sed), virtual/awk (awk), sys-apps/grep (grep), sys-apps/coreutils (tr, expr), net-analyzer/arping (arping) | ||
| drm | Includes kernel modules that provides DRM support | when required | |||
| dm | Adds support of device-mapper | when required | sys-fs/lvm2 (dmsetup) | ||
| kernel-network-modules | Includes and loads kernel modules for network devices | when required | |||
| nvdimm | Adds support for non-volatile DIMM devices | when required; hostonly: rootfs or there nvdimm devices in system - always | |||
| debug | Enable debug features | when required | |||
| virtfs | Adds virtual filesystems (9p) support | when required; hostonly: rootfs | |||
| securityfs | Arranges for the securityfs to be mounted early | when required | |||
| masterkey | Includes masterkey that can be used to decrypt other keys | when required | ?? (keyctl uname) | ||
| pollcdrom | Enables CD-ROM polling | when required | |||
| selinux | Arranges for the selinux policy to be loaded | when required | |||
| syslog | Includes syslog capabilites to initramfs | when required | |||
| img-lib | Includes various tools for decompressing images | when required | ?? (tar gzip dd echo tr) |
- The Enabled field indicates when a particular module will be included by default into the initramfs image.
- Modules with pre-requisite packages cannot be included (even explicitly) if the required software is missing from the host.
- Modules enabled for "host-only: rootfs" are included in host-only images if the active rootfs requires that module.
- Modules enabled "when required" may be installed as dependency or when explicitly added via the command-line or configuration file.
Customizing the image
Besides defining the list of modules to include, the final initramfs may be customized in a few other ways. The install_items option in the configuration file can list a number of arbitrary items to add to the image. Other options add specific elements to the image, as described below.
Adding files to the image
It is possible to add multiple files to the initramfs image. For example, adding two firmware files can be achieved via:
/etc/dracut.conf.d/firmware.confinstall_items+=" /lib/firmware/i915/kbl_guc_ver9_33.bin /lib/firmware/i915/kbl_huc_ver01_07_1398.bin "
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.) 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.
/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
filesystemsparameter.
Filesystems and mount points
The default image will arrange for the rootfs and the /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 the desired behavior, or other partitions may need to be mounted as well. To just have additional partitions mounted at boot, add them under:
/etc/dracut.conf# Bring up <device> in initramfs, <device> should be the device name
add_device+=" /dev/mapper/sysvg-home /dev/mapper/sysvg-swap /dev/mapper/hdvg-private "
To further alter the behavior of the initramfs the fstab-sys module is required, plus 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 the 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 the initramfs' /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.)
Elogind
To fully support elogind, an extra command should be added to the initramfs via the dracut configuration:
/etc/dracut.conf.d/elogind.confinstall_items+=" /lib64/elogind/elogind-uaccess-command "
This path will be /lib/elogind/elogind-uaccess-command on architectures which do not have /lib64 for their native libraries.
This path will be /usr/lib/elogind/elogind-uaccess-command starting from sys-auth/elogind-255.5 with split-usr type profile.
This will allow uaccess rules to be processed correctly.
Compressing the image
For zstd, refer to Zstd. Dracut uses app-arch/lbzip2 if available for bzip2 or app-arch/pigz if available for gzip. By default, file systems are compressed with gzip.
For a working system that will boot, compile the userspace compression program AND the kernel with decompression.
/etc/dracut.conf.d/compression.conf# Choose compression program for the image
compress="gzip"
Booting the initramfs
Any parameters that are need to pass to the dracut modules are passed on the kernel command line. If 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 man page.
Tasks
ext boot
For booting an ext(2,3,4) filesystem none of the optional dracut modules are required.
root #dracut -m "rootfs-block base" initramfs.imgOnce the image is built, the final step is to include the image in the bootloader. To do this, simply add a line in grub.conf:
/boot/grub/grub.confkernel /boot/vmlinuz root=UUID=00000000-0000-0000-0000-000000000000
initrd /boot/initramfs.img
It is recommended to use the UUID= (or LABEL=) form of the root specification; to guard against device names changing between boots. Find the UUID of the root device by running this command:
root #ls -alF /dev/disk/by-uuidLVM on LUKS
To boot from a root residing on an LVM volume located inside of an encrypted LUKS container these kernel command line options can be used: root=UUID=<root volume UUID> rd.luks.uuid=<LUKS partition UUID> rd.lvm.vg=<volume group name>. And to enable discard rd.luks.allow-discards is needed. rd.lvm.vg might not be need depending on specific configuration but might lead to not all LVM partitions being activated. If for example the system has the following partitions:
root #blkid/dev/sda1: UUID="2acb7668-fff1-492d-b46e-f05ead26d153" TYPE="crypto_LUKS" PARTUUID="cbe8be3c-3bcf-0d44-9f7b-27c7ad4dd9f6" /dev/mapper/luks-2acb7668-fff1-492d-b46e-f05ead26d153: UUID="19Mtok-zEfG-7JXI-GXvM-Neoz-JnST-vwNlO3" TYPE="LVM2_member" /dev/mapper/Vg-root: UUID="199bb83d-c783-4254-a6eb-fdbb83c33144" TYPE="ext4"
the kernel command line options will look like root=UUID=199bb83d-c783-4254-a6eb-fdbb83c33144 rd.luks.uuid=2acb7668-fff1-492d-b46e-f05ead26d153 rd.lvm.vg=Vg.
In some instances it might not work to add
root option, as Dracut also adds the default on its own. This could result in a duplication that will cause the kernel to fail.NFS boot
Warning: Currently Dracut does not have a proper network useflag (see Bug 590566), so make sure that "net-analyzer/arping" is not installed, but instead "net-misc/iputils[arping]".
For an NFS boot, only 3 modules and the nfs dracut module are required:
root #dracut -m "nfs network base" initramfs-nfs-only.imgBooting is done with the following line in the 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>
/var/lib/tftpboot/pxelinux.cfg/default...
APPEND initrd=initramfs-nfs-only.img rd.ip=auto root=dhcp
...
For more specific problems, consult official Dracut page at Fedora Wiki:
NBD boot
For an NBD boot, only 3 modules and the nbd dracut module are needed:
root #dracut -m "nbd network base" initramfs-nbd-only.imgBooting is done with the following line in the 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>
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.
/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 partitioned 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.
/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>
...
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. Enable the debug USE flag:
root #dracut -m "<other modules>" initramfs-with-debug-only.imgUsing the rd.debug flag, all Dracut commands are shown. When dropped to the Dracut shell, the logfile will be available in /run/initramfs/init.log.
/var/lib/tftpboot/pxelinux.cfg/default...
APPEND initrd=initramfs-with-debug.img rd.debug
...
In order to be dropped to a shell when mounting the root filesystem fails, the rd.shell kernel cmdline flag has to be enabled. To force dropping to a shell before mount, set the rd.break=mount flag. See the manpage of dracut.cmdline for more options.
It is possible that the typed characters are not being displayed when you are in the rescue shell. An attempt at fixing this with
stty echo or reset results in error message unable to perform all requested operations. This is caused by plymouth, and can be fixed by blindly typing plymouth quit and running the command.[1]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.imgCustom modules
A quick Dracut module
See Rich0's Gentoo Blog for now.
See also
- Genkernel — a tool created by Gentoo used to automate the build process of the kernel and initramfs.