dracut

From ArchWiki

dracut creates an initial image used by the kernel for preloading the block device modules (such as IDE, SCSI or RAID) which are needed to access the root filesystem. Upon installing linux, you can choose between mkinitcpio and dracut. dracut is used by Fedora, RHEL, Gentoo, and Debian, among others. Arch uses mkinitcpio by default.

You can read the full project documentation for dracut in the documentation.

Installation

Install the dracut package, or dracut-gitAUR for the latest development version.

Tip: If dracut works on your machine after you test it, you can uninstall mkinitcpio.

Usage

dracut is easy to use and typically does not require user configuration, even when using non-standard setups, like LVM on LUKS.

To generate an initramfs for the running kernel:

# dracut --hostonly --no-hostonly-cmdline /boot/initramfs-linux.img

To generate a fallback initramfs run:

# dracut /boot/initramfs-linux-fallback.img

/boot/initramfs-linux.img refers to the output image file. If you are using the non-regular kernel, consider changing the file name. For example, for the linux-lts kernel, the output file should be named /boot/initramfs-linux-lts.img. However, you can name these files whatever you wish as long as your boot loader configuration uses the same file names.

Note:
  • The files created through these commands embed any installed Microcode images.
  • Due to FS#59841, the hostonly mode includes all Intel microcode in the initramfs, not just that which is needed by the system.[1]

Additional options

The --force flag overwrites the image file if it is already present.

The --kver option specifies which kernel to use. The argument to this option must match the name of a directory present in /usr/lib/modules.

More flags can be found with dracut(8).

Advanced configuration

dracut can be configured by directly passing arguments on the command line (see dracut(8) § OPTIONS). If you wish to always execute dracut with a certain set of flags, you can save a specified configuration in a .conf file in /etc/dracut.conf.d/. For example:

/etc/dracut.conf.d/myflags.conf
hostonly="yes"
compress="lz4"
add_drivers+=" i915 "
omit_dracutmodules+=" network iscsi "

You can see more configuration options with dracut.conf(5). Fuller descriptions of each option can be found with dracut(8). We will describe a few common options in what follows.

Dracut modules

dracut uses a modular approach to build the initramfs (see dracut.modules(7)). All of dracut 's builtin modules are located in /lib/dracut/modules.d and can be listed with dracut --list-modules. Extra modules can be provided by external packages e.g. dracut-sshd-gitAUR. dracut 's built-in modules unfortunately lack documentation, although their names can be self-explanatory.

Some of the modules are active/inactive by default, and can be activated/deactivated with --add/--omit command line argument or with the add_dracutmodules+=""/omit_dracutmodules+="" persistent config entry lines.

/etc/dracut.conf.d/myflags.conf
# ...
add_dracutmodules+=" <dracut modules to activate> "
omit_dracutmodules+=" <dracut modules to deactivate> "
# ...

TPM2

To make use of systemd 's unlocking of luks2 encrypted volumes using TPM2 through systemd-cryptenroll, install tpm2-tools package and enable the tpm2-tss dracut module.

Early kernel module loading

Dracut enables early loading (at the initramfs stage, via modprobe) through its --force_drivers command or force_drivers+="" config entry line. For example:

/etc/dracut.conf.d/myflags.conf
# ...
force_drivers+=" nvidia nvidia_modeset nvidia_uvm nvidia_drm "
# ...

Kernel command line options

Kernel command line options can be placed in a .conf file in /etc/dracut.conf.d/, and set via the kernel_cmdline= flag. Dracut will automatically source this file and create a 01-default.conf file and place it inside the initramfs directory /etc/cmdline.d/. For example, your kernel command line options file could look like:

/etc/dracut.conf.d/cmdline.conf
kernel_cmdline="rd.luks.uuid=luks-f6c738f3-ee64-4633-b6b0-eceddb1bb010 rd.lvm.lv=arch/root rd.lvm.lv=arch/swap  root=/dev/arch/root rootfstype=ext4 rootflags=rw,relatime"

Miscellaneous notes

It is not necessary to specify the root block device for dracut. From dracut.cmdline(7):

The root device used by the kernel is specified in the boot configuration file on the kernel command line, as always.

However, it may be useful to set some parameters early, and you can enable additional features like prompting for additional command line parameters. See dracut.cmdline(7) for all options. Here are some example configuration options:

  • Resume from a swap partition: resume=UUID=80895b78-7312-45bc-afe5-58eb4b579422
  • Prompt for additional kernel command line parameters: rd.cmdline=ask
    Warning: rd.cmdline=ask may cause an issue where the keyboard is not yet initialized prior to its prompt forcing a hard reset. See dracut issue 728.
  • Print informational output even if quiet is set: rd.info

Unified kernel image

dracut can produce unified kernel images with the --uefi command line option or with the uefi="yes" configuration option.

Tips and tricks

View information about generated image

You can view information about a generated initramfs image, which you may wish to view in a pager:

# lsinitrd /path/to/initramfs_or_uefi_image | less

This command will list the arguments passed to dracut when the image was created, the list of included dracut modules, and the list of all included files.

Change compression program

To reduce the amount of time spent compressing the final image, you may change the compression program used.

Warning:
  • Make sure your kernel has your chosen decompression support compiled in, otherwise you will not be able to boot. You must also have the chosen compression program package installed.
  • The upstream Linux kernel does not support zstd compressed initramfs before version 5.9. linux-zen supports it since version 5.8

Simply add any one of the following lines (not multiple) to your dracut configuration:

compress="cat"
compress="gzip"
compress="bzip2"
compress="lzma"
compress="xz"
compress="lzo"
compress="lz4"
compress="zstd"

gzip is the default compression program used. compress="cat" will make the initramfs with no compression.

You can also use a non-officially-supported compression program:

compress="program"

Generate a new initramfs on kernel upgrade

It is possible to automatically generate new initramfs images upon each kernel upgrade. The instructions here are for the default linux kernel, but it should be easy to add extra hooks for other kernels.

Tip:

As the command to figure out the kernel version is somewhat complex, it will not work by itself in a pacman hook. So create a script anywhere on your system. For this example it will be created in /usr/local/bin/.

The script will also copy the new vmlinuz kernel file to /boot/, since the kernel packages do not place files in /boot/ anymore.[2]

/usr/local/bin/dracut-install.sh
#!/usr/bin/env bash

args=('--force' '--no-hostonly-cmdline')

while read -r line; do
	if [[ "$line" == 'usr/lib/modules/'+([^/])'/pkgbase' ]]; then
		read -r pkgbase < "/${line}"
		kver="${line#'usr/lib/modules/'}"
		kver="${kver%'/pkgbase'}"

		install -Dm0644 "/${line%'/pkgbase'}/vmlinuz" "/boot/vmlinuz-${pkgbase}"
		dracut "${args[@]}" --hostonly "/boot/initramfs-${pkgbase}.img" --kver "$kver"
		dracut "${args[@]}" --no-hostonly "/boot/initramfs-${pkgbase}-fallback.img" --kver "$kver"
	fi
done
/usr/local/bin/dracut-remove.sh
#!/usr/bin/env bash

while read -r line; do
	if [[ "$line" == 'usr/lib/modules/'+([^/])'/pkgbase' ]]; then
		read -r pkgbase < "/${line}"
		rm -f "/boot/vmlinuz-${pkgbase}" "/boot/initramfs-${pkgbase}.img" "/boot/initramfs-${pkgbase}-fallback.img"
	fi
done

You need to make the scripts executable. If you wish to add or remove flags, you should add them to your dracut configuration.

The next step is creating pacman hooks:

/etc/pacman.d/hooks/90-dracut-install.hook
[Trigger]
Type = Path
Operation = Install
Operation = Upgrade
Target = usr/lib/modules/*/pkgbase

[Action]
Description = Updating linux initcpios (with dracut!)...
When = PostTransaction
Exec = /usr/local/bin/dracut-install.sh
Depends = dracut
NeedsTargets
/etc/pacman.d/hooks/60-dracut-remove.hook
[Trigger]
Type = Path
Operation = Remove
Target = usr/lib/modules/*/pkgbase

[Action]
Description = Removing linux initcpios...
When = PreTransaction
Exec = /usr/local/bin/dracut-remove.sh
NeedsTargets

You should stop mkinitcpio from creating and removing initramfs images as well, either by removing mkinitcpio or with the following commands:

# ln -sf /dev/null /etc/pacman.d/hooks/90-mkinitcpio-install.hook
# ln -sf /dev/null /etc/pacman.d/hooks/60-mkinitcpio-remove.hook

Bluetooth keyboard support

Dracut will enable the bluetooth module automatically when a bluetooth keyboard is detected. However it is required that dracut is in hostonly mode for this. This seems to not be the default. To enable hostonly mode you can add the following to your dracut configuration:

hostonly=yes

Optional dependencies

This article or section is being considered for removal.

Reason: Optional dependencies are a part of the pacman package. Any missing in dracut should be reported in [3] (Discuss in Talk:Dracut)


Some Dracut functionality requires optional packages installed. The table below lists all optional packages that Dracut can take advantage of.

package feature
binutils --uefi option support
bluez bluetooth (keyboard)
btrfs-progs scan for Btrfs on block devices
busybox allows use of busybox (on your own risk)
bzip2 bzip2 compression
cifs-utils support CIFS
connman support for connman networking
dash allows use of dash (on your own risk)
dhclient legacy networking support
dmraid dmraid dracut module support
e2fsprogs ext2/3/4 filesystem support
elfutils strip binaries to reduce initramfs size
multipath-tools multipath dracut module support
f2fs-tools fsfs filesystem support
fuse3 live on NTFS (dmsquash-live-ntfs module)
iproute2 legacy networking support
iputils networking support
lvm2 support Logical Volume Manager
lzop lzop compression
mdadm support MD devices, also known as software RAID devices
memstrackAUR memstrack module support
multipath-tools support Device Mapper multipathing
nbd support network block devices
ndctl NVDIMM support
networkmanager networkmanager support
nfs-utils support NFS
ntfs-3g live on NTFS (dmsquash-live-ntfs module)
nvme-cli NVMe-oF support (nvmf module)
open-iscsi support iSCSI (iscsi module)
openssh install ssh and scp along with config files and specified keys (ssh-client module)
pigz faster gzip compression
sbsigntools uefi_secureboot_cert/key configuration option support)
plymouth plymouth boot splash
rng-tools enable rngd service to help generating entropy early during boot
rsyslogAUR enable logging with rsyslog
sbsigntools uefi_secureboot_cert/key configuration option support
squashfs-tools support for building a squashed initramfs
tar live tar image
tpm2-tools tpm2-tss module support)

Troubleshooting

Hibernation

If resuming from hibernation does not work, you may need to configure dracut to include the resume module. You will need to add a configuration file:

/etc/dracut.conf.d/resume-from-hibernate.conf
add_dracutmodules+=" resume "

This article or section is being considered for removal.

Reason: Fixed via MR 6. (Discuss in Talk:Dracut)

With version 255, systemd reorganized how it resumes from hibernation, and a new service file systemd-hibernate-resume.service must be included in the initramfs, dracut currently does not include this file (see bug progress). For now the situation can be remedied by explicitly including this service file:

/etc/dracut.conf.d/resume-from-hibernate.conf
add_dracutmodules+=" resume "
install_items+=" /usr/lib/systemd/system/systemd-hibernate-resume.service "

LVM / software RAID / LUKS

If the kernel has issues auto discovering and mounting LVM / software RAID / LUKS blocks. You can retry generating an initramfs with the following kernel command line options:

rd.auto rd.lvm=1 rd.dm=1 rd.md=1 rd.luks=1

A stop job is running for "brltty"

If you have issues booting or very long shutdown processes while the system waits for brllty, add the following to the dracut configuration line:

omit_dracutmodules+=" brltty "

Alternatively, uninstall brltty if it is not needed.

No usable keyslot is available

Cannot use whirlpool hash for keyslot encryption. 
Keyslot open failed. 
No usable keyslot is available.

A failure to boot with a message similar to the above typically will only require the user to include the crypt module via add_dracutmodules. However, if you continue to get the message after adding it, you may need to adjust your configuration with the following.

install_items+=" /usr/lib/ossl-modules/legacy.so "

This is because OpenSSL deprecated the whirlpool hash and moved it to that library. Dracut does not automatically gather it when using Arch.

See also