dracut

Related articles
booster
mkinitcpio
Unified kernel image
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
,
booster
, and
dracut
.
dracut
is used by Fedora, RHEL and Gentoo, among others. Arch uses
mkinitcpio
by default.
You can read the full project documentation for
dracut
in the documentation
.
Installation
Install
the
dracut
package.
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 --add-confdir no-network /boot/initramfs-linux.img
Note
In some cases, especially when installing a system for the first time, the above command will not work. Use the following:
# dracut -f --regenerate-all
To generate a fallback initramfs run:
# dracut -f --add-confdir rescue /boot/initramfs-linux-fallback.img
Note that starting from v108 of dracut, in usual configuration fallback initramfs should not be needed as the default initramfs has most of the kernel drivers already included.
/boot/initramfs-linux.img
refers to the output image file. If you are using an other 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.
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-git
AUR
.
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
"
# ...
For dracut module documentation, see the
upstream dracut documentation
.
Most dracut modules are dependent on other dracut modules. As an example the bluetooth dracut module depends on the dbus dracut module.
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
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.
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 of 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-cpio
option 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 adding
busybox
dracut module to replace bash.
Consider
hostonly
and
hostonly_mode=strict
.
Generate a new initramfs on kernel upgrade
The
dracut
package include hooks for pacman to automatically generate new initramfs images upon each kernel upgrade.
If KERNEL_INSTALL_INITRD_GENERATOR is set on the host system the dracut hook will not generate an initramfs with dracut.
Tip
The
dracut-ukify
AUR
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
by configuring the key and cert in /etc/dracut-ukify.conf (Note that it cannot use them if configured in
dracut
's config folder). It's able to generate initramfs images that are 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
. Note that when using these, the
90-dracut-install
hook may still generate non-EFI initramfs images in
/boot/
, such as
initramfs-linux.img
. These may not be used for anything and therefore waste space in the ESP partition. To stop these images from being created, run
touch /etc/pacman.d/hooks/90-dracut-install.hook
as root.
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. To enforce the module addition see
Dracut#dracut_modules
.
However it is required that dracut is in hostonly mode for dracut to auto-discover bluetooth keyboard.
Limine boot loader support
The
limine-dracut-support
AUR
package utilizes
limine-entry-tool
with dracut and pacman hooks to automate the installation and removal of kernels and boot entries in the
Limine
boot loader
. See
Limine#Boot entry automation
for more information.
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
.
See also
Wikipedia:dracut (software)
Gentoo:Dracut