dracut
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.
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 --add-confdir no-network /boot/initramfs-linux.img
To enable hostonly mode permanently (so that you do not need to include it in the command line) you can add the following to your dracut configuration:
/etc/dracut.conf.d/hostonly.conf
hostonly="yes"
# dracut --regenerate-all
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.
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
It is important to note that there are two distinct approaches how the various tasks during initial ramdisk phase are performed:
- Shell (bash/busybox/dash) based initial ramdisk
- An init script is started that in turn scans the filesystem of the initial ramdisk for dracut scripts to be executed.
- systemd based (default) initial ramdisk
- systemd is already started at the beginning of the initial ramdisk phase. The tasks to be executed are determined by regular systemd unit files. See systemd bootup process.
The concrete variant is determined by the absence or presence of the systemd dracut module. See #dracut modules for more details.
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+=" systemd network "
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 " # ...
The following table lists dracut modules, required packages (dracut 's optional dependencies) and module descriptions.
Most dracut modules are dependent on other dracut modules. As an example the bluetooth dracut module depends on the dbus dracut module. The table below only lists direct dracut module dependencies, i.e. the required packages for a given module listed in the module-setup.sh for the given dracut module.
For additional dracut module documentation, see the upstream dracut wiki.
| dracut module | Required packages | Description |
|---|---|---|
| bluetooth | bluez | Bluetooth (keyboard) |
| btrfs | btrfs-progs | Scans for Btrfs on block devices |
| busybox | busybox | Allows use of BusyBox (on your own risk) |
| crypt | cryptsetup | Support for encrypted Dm-crypt file systems |
| dash | dash | Allows use of Dash (on your own risk) |
| dmraid | dmraid, multipath-tools | dmraid dracut module support |
| multipath | multipath-tools | Multipath dracut module support |
| dmsquash-live-ntfs | fuse3, ntfs-3g | Live on NTFS |
| lvm | lvm2 | Support for LVM |
| mdraid | mdadm | Support MD devices, also known as software RAID devices |
| memstrack | memstrackAUR | Support memstrack |
| nvdimm | ndctl | NVDIMM support |
| plymouth | plymouth | Plymouth boot splash |
| rescue | Includes various utilities for rescue mode (such as ping, ssh, vi, fsck.*) | |
| resume | Allows initramfs to resume from low-power state | |
| rngd | Starts random generator service on early boot | |
| syslog | rsyslogAUR | Enable logging with Rsyslog |
| squash | squashfs-tools | Support for building a squashed initramfs |
| tpm2-tss | tpm2-tools | Trusted Platform Module |
| base | Base module with required utilities | |
| bash | bash | Bash is the preferred interpreter, if there are more available |
| biosdevname | biosdevnameAUR | Enables BIOS network device renaming |
| caps | Supports dropping capabilities before init | |
| convertfs | Merges / into /usr on next boot | |
| crypt-gpg | gnupg | Adds support GPG for crypto operations and SmartCards (may requires GPG keys) |
| crypt-loop | Adds support for encrypted loopback devices (symmetric key) | |
| dbus | Virtual package for dbus-broker or dbus-daemon | |
| dbus-broker | dbus-broker | Use dbus-broker as dbus service provider |
| dbus-daemon | dbus | Use dbus as dbus service provider |
| debug | Enable debug features | |
| dm | Adds support of device-mapper | |
| dmsquash-live-autooverlay | Creates a partition for overlayfs usage in the free space on the root filesystem's parent block device | |
| dracut-systemd | Base systemd dracut module | |
| drm | Includes kernel modules that provides DRM support | |
| ecryptfs | Adds ecryptfs filesystems support | |
| fido2 | Allows to unlock an encrypted filesystem using a FIDO2 security token | |
| fips | Enforces FIPS security standard regulations | |
| fs-lib | Library for filesystem tools (including fsck.* and mount) | |
| fstab-sys | Arranges for arbitrary partitions to be mounted before rootfs | |
| i18n | Includes keymaps, console fonts, etc. | |
| img-lib | Library to includes various tools for decompressing images | |
| integrity | Adds support for Extended Verification Module | |
| kernel-modules | Kernel modules for root filesystems and other boot-time devices | |
| kernel-modules-extra | Extra out-of-tree kernel modules | |
| lunmask | Masks LUN devices to select only ones which required to boot | |
| lvmmerge | Merges lvm snapshots | |
| lvmthinpool-monitor | Monitor LVM thinpool service | |
| masterkey | Masterkey that can be used to decrypt other keys and keyutils | |
| modsign | Adds signing kernel modules support | |
| overlayfs | Kernel module for overlayfs | |
| pcsc | Adds support for PCSC Smart cards | |
| pkcs11 | Includes PKCS#11 libraries | |
| pollcdrom | Enables CD-ROM polling | |
| qemu | Includes kernel modules for QEMU environment | |
| rescue | utilities for rescue mode (such as ping, ssh, vi, fsck.*) | |
| rootfs-block | Arranges for the block device containing the rootfs to be mounted | |
| securityfs | Arranges for the securityfs to be mounted early | |
| selinux | Arranges for the selinux policy to be loaded | |
| shutdown | Sets up hooks to run on shutdown | |
| systemd | Adds systemd as early init initialization system | |
| terminfo | Includes a terminfo file | |
| udev-rules | Includes udev and some basic rules | |
| uefi-lib | Library to include UEFI tools | |
| usrmount | Mounts /usr | |
| virtfs | Adds virtual filesystems (9p) support | |
| virtiofs | Adds virtiofs filesystems support | |
| warpclock | Sets kernel's timezone and reset the system time if adjtime is set to LOCAL | |
| watchdog | Includes watchdog devices management; works only if systemd not in use | |
| watchdog-modules | Includes watchdog kernel modules to be loaded early in booting |
Dracut modules that are meant to be used when IP address is expected to be available during early boot.
| networking dracut module | Required packages | Description |
|---|---|---|
| cifs | cifs-utils | Support for Samba |
| nbd | nbd | Support network block devices |
| network-manager | networkmanager | NetworkManager support |
| nfs | nfs-utils | NFS support - NFSv3 and NFSv4 |
| nvmf | nvme-cli, jq | NVMe over Fibre Channel and NVMe-over Fabrics support |
| iscsi | open-iscsi | ISCSI support |
| ssh-client | openssh | Installs ssh and scp along with config files and specified keys |
| network-legacy | dhclient, iproute2, iputils | Legacy network support |
| connman | connman | Support for ConnMan networking |
| kernel-network-modules | Includes and loads kernel modules for network devices | |
| livenet | Fetch live updates for SquashFS images | |
| network | Virtual module for network service providers | |
| url-lib | Library to includes curl and SSL certs | |
| qemu-net | Includes network kernel modules for QEMU environment | |
| systemd-network-management | Adds network management for systemd. Includes systemd-networkd, systemd-resolved and some othr networking related dracut modules | |
| systemd-networkd | Systemd-networkd | |
| net-lib | Networking library with ip |
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 - Print informational output even if
quietis 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.
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"
Performance considerations
Some considerations to optimize the boot and initramfs creation performance are:
- Understand and configure the fastest compression. If the kernel modules are already compressed, perhaps there is no need to re-compress the initramfs on creation.
- Understand the impact if including systemd into your initramfs. If it slows things down, omit it. If it makes things faster, include it.
- Consider using dracut-cpio when using a copy-on-write filesystem. See the
--enhanced-cpiooption for applicability.
- Minimize the number of kernel modules and dracut modules included in initramfs. As an example: If nfs-utils is installed (but not required to boot), then you need to explicitly omit the nfs dracut module, otherwise network boot will be enabled in the generated initramfs in default configuration - see https://github.com/dracut-ng/dracut-ng/pull/297.
- Consider using busybox instead of bash.
- Consider hostonly.
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.
- The dracut-ukifyAUR package is the modern way to generate a unified kernel image using systemd-ukify. Unlike the methods below, you can sign your whole kernel image including the initramfs. Using the
uefi_secureboot_certanduefi_secureboot_keyoptions in your dracut config (dracut.conf(5)). - The dracut-hookAUR package includes hooks and scripts similar to the below. Alternatively, you may want dracut-uefi-hookAUR or dracut-hook-uefiAUR instead, if you want an initramfs image that is an EFI executable (i.e.
esp/EFI/Linux/linux-kernel-machine_id-build_id.efi). EFI binaries in this directory are automatically detected by systemd-boot and therefore do not need an entry in/boot/loader/loader.conf.
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.[1]
/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[@]}" --add-confdir rescue "/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.
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 "
If applicable to your system, you may also want to see instructions to resume from an encrypted swap partition including the dracut specific instructions.
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 brltty, 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.