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.
- 1 Installation
- 2 Building an initramfs image
- 3 Adding modules
- 4 List of modules
- 5 Booting the initramfs
- 6 Tasks
- 7 Custom modules
- 8 See also
- 9 External resources
Before you can use 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 --ask sys-kernel/dracut
Building an initramfs image
Once you have installed dracut, you can use it to build an initramfs image. The simplest way to do this is to just run
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:
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. You can set hostonly mode as the default in /etc/dracut.conf.
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. 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. To override the kernel version and keep the default file name, add the --kver option:
dracut --hostonly --kver 3.2.5-hardened
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.
Dracut comes with a suitable set of default modules (see below). 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:
# 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 option) will override the entire default list, and install only the modules specified. This can cut down significantly on image size (for example, if you don't need any kernel modules, or i18n support, etc.). If you are not 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 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
An incomplete list of modules is below, with their additional requirements.
|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
|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|
|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.||systemd not in use||sys-libs/libcap (also replaces |
|crypt||Supports an encrypted rootfs.||host-only: rootfs||sys-fs/cryptsetup|
|crypt-gpg||Use gpg for crypt support (requires
||never (see note below)||app-crypt/gnupg|
|dmraid||Support rootfs on FakeRAID.||host-only: rootfs||sys-fs/multipath-tools, sys-fs/dmraid|
|dmsquash-live||Supports LiveCD rootfs.||never (host-only: refused)|
|gensplash||Include a static splash screen.||never||media-gfx/splashutils|
|iscsi||Supports rootfs on iscsi devices.||host-only: rootfs||sys-block/open-iscsi|
|livenet||Retrieve rootfs over HTTP. (requires
|lvm||Supports rootfs on LVM device.||host-only: rootfs||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||sys-block/nbd|
|nfs||Supports NFS-mounted rootfs.||host-only: rootfs||net-fs/nfs-utils net-nds/rpcbind|
|plymouth||Includes boot animation.||always||sys-boot/plymouth|
|ssh-client||Includes ssh and scp clients.||never||dev-libs/openssl|
|syslog||Includes remote logging support.||never||app-admin/syslog-ng or rsyslog|
|debug||Includes useful troubleshooting tools.||never||installed when
|dm||Includes device-mapper.||never||sys-fs/device-mapper or sys-fs/lvm2|
|ifcfg||Generates network config at runtime.||never|
|network||Brings up network for net booting.||always||net-misc/dhcp, sys-apps/iproute2|
|selinux||Arranges for the selinux policy to be loaded.||installed when
|url-lib||Includes cUrl and SSL certs.||never||net-misc/curl|
- 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.
- sys-boot/plymouth requires that x11-libs/libdrm be built with the
- The additional packages require that one or more dependency libraries be built with the
- 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.
crypt-gpgdoes not seem to have any effect on systemd. This is because crypto volumes are activated by systemd services. However, systemd will only ask once for the password if several volumes use the same password.
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:
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
# 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 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. To just have additional partitions mounted at boot you can add them under
# 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 one needs the
fstab-sys module, and the following options:
- Create a file called /etc/fstab.sys, which will be copied to the initramfs and mounted.
--use-fstab), which will use your system's /etc/fstab instead of /proc/self/mountinfo
--add_fstab filename, which will add the contents of filename to the initramfs's /etc/fstab.
--mount fstab mount spec, which adds individual entries into your initramfs' /etc/fstab.
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.
For booting an ext(2,3,4) filesystem you don't need any of the optional dracut modules.
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:
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:
ls -alF /dev/disk/by-uuid
LVM 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>.
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:
/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
rootoption as Dracut also adds the default on its own. You might end up with a duplication that will cause the kernel to fail.
Warning: Currently Dracut does not have a proper network useflag (see Bug 590566), so you need to make sure that you do not have "net-analyzer/arping" installed, but instead "net-misc/iputils[arping]".
For an NFS boot, you need only 3 modules and the nfs dracut module.
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>
... APPEND initrd=initramfs-nfs-only.img rd.ip=auto root=dhcp ...
For more specific problems, consult official Dracut page at Fedora Wiki:
For an NBD boot, you need only 3 modules and the nbd dracut module.
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>
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.
... 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.
... 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.
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.
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.
... APPEND initrd=initramfs-with-debug.img rd.debug ...
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.
dracut -m "kernel-modules base" --filesystems "squashfs" initramfs-with-squashfs.img
A quick Dracut module
See Rich0's Gentoo Blog for now.
- Genkernel — a tool created by Gentoo used to automate the build process of the kernel and initramfs.