Dracut

USE flags

Some packages are aware of the dracut USE flag.

Kernel

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

Default images

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:

Modules

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.

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:

# 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"

# 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 "

install_items="/lib64/elogind/elogind-uaccess-command"

# Choose compression program for the image
compress="gzip"

ext boot

For booting an ext(2,3,4) filesystem you don't need any of the optional dracut modules.

Once you have the image built, the final step is to include the image in the bootloader. 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:

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>. 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:

/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.

NFS boot

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.

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:

• https://fedoraproject.org/wiki/Dracut/Options#NFS

NBD boot

For an NBD boot, you need only 3 modules and the nbd dracut module.

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>

...
 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>
...

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.

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

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.

A quick Dracut module

See Rich0's Gentoo Blog for now.