Dracut Initramfs infrastructure

Linux
Published

November 5, 2015

Modified

October 22, 2024

Event-driven software to build initrd images:

https://dracut.wiki.kernel.org
https://github.com/dracutdevs/dracut/wiki

Used a container to work on Dracut….

toolbox create --container dracut
toolbox enter dracut
sudo dnf install -y dracut NetworkManager
exit

Usage…

dracut --help | grep Version                   # show program version
## configuration files
man dracut.conf                                # manual
/etc/dracut.conf                               # global
{/etc,/usr/lib}/dracut.conf.d/*.conf           # custom (/etc overwrites /usr/lib)
## command
dracut --kver $(uname -r)                      # generate the image at the default location for a specific kernel version 
dracut -fv <path>                              # create a new initramfs at specified path
lsinitrd | less                                # contents of the default image
lsinitrd -f <path>                             # content of a file within the default image
lsinitrd <path>                                # contents of a specified initramfs image
## boot parameters
dracut --print-cmdline                         # kernel command line from the running system
man dracut.cmdline                             # list of all kernel arguments

Troubleshooting:

## enable logging within the initramfs image
>>> cat /etc/dracut.conf.d/log.conf
logfile=/var/log/dracut.log
fileloglvl=6
## rebuild the image

Boot Stages

The bootloader loads the kernel and its initramfs….

  • …kernel unpacks the initramfs and executes /init…
  • Find more comprehensive information in the man dracut.bootup.

Init runs following phases…

Phase Hooks Comment
Setup cmdline Source dracut-lib.sh, start logging if requested, parse the kernel arguments
Udev pre-udev, pre-trigger Start udevd, run udevadm trigger, load kernel modules
Main initqueue Wait for devices until initqueue/finished
Mount pre-mount, mount, pre-pivot Mount root device, check for target /init
Switch cleanup Clean up, stop udev, stop logging. Start target /init

Modules

Dracut builds the initramfs out of modules:

  • Each prefixed with a number which determines the order during the build.
  • Lower number modules have higher priority (can’t be overwritten by subsequent modules)
  • Builtin modules are numbered from 90-99
man dracut.modules                             # documentation
ls -1 /usr/lib/dracut/modules.d/**/*.sh        # modules with two digit numeric prefix, run in ascending sort order
dracut --list-modules | sort | less            # list all available modules
dracut --add <module> ...                      # add module to initramfs image
## within the build initramfs
/usr/lib/dracut/hooks/                         # all hooks

All module installation information is in the file module-setup.sh with following functions:

Function Description
check() Check if module should be included
depends() List other required modules
cmdline() Required kernel arguments
install() Install non-kernel stuff (scripts, binaries, etc)
installkernel() Install kernel related files (e.g drivers)

Debug Shell

…useful to get a shell inside the initrd environment…

  • rd.shell dropping to a shell, if root mounting fails
  • rd.debug…std{out,err} to /run/initramfs/rdsosreport.txt
    • set -x for the dracut shell
    • Systemd logs to to journal…
    • …without dmesg in /run/initramfs/init.log

rd.break always drop to shell at the end…

  • …before control is passed to the init process in the real root file-system
  • rd.break= at a defined breakpoint (cf. following list)
{cmdline|pre-udev|pre-trigger|initqueue|pre-mount|mount|pre-pivot|cleanup}

Network

Create a network aware initramfs with the dracut-network package:

Kernel Command-Line

Check /proc/cmdline in an emergency shell

# execute kernel command-line processing in an emergency shell
dracut-cmdline

Two syntaxes to specify network configuration for an interface

ip=<interface>:{dhcp|on|any|dhcp6|auto6}[:[<mtu>][:<macaddr>]]
ip=<client-IP>:[<peer>]:<gateway-IP>:<netmask>:<client_hostname>:<interface>:{none|off|dhcp|on|any|dhcp6|auto6|ibft}[:[<mtu>][:<macaddr>]]

Network related command-line arguments, cf. dracut.cmdline:

  • rd.driver.post=mlx4_ib,ib_ipoib,ib_umad,rdma_ucm…load additional kernel modules
  • rd.neednet=1…force network configuration without a network root netroot=
  • rd.retry=80…wait until the interfaces becomes ready
  • Supports adding…
    • nameserver=10.20.1.11 a DNS server
    • rd.route=10.20.0.0/16:10.20.0.1:ib0…custom routes

NetworkManager

Check if a configuration is present in /run/NetworkManager/system-connections

Generated by /usr/libexec/nm-initrd-generator 1 parses the kernel command-line

# debug a kernel command line...
/usr/libexec/nm-initrd-generator --stdout -- ip=ib0:dhcp

# ....more complex example...
/usr/libexec/nm-initrd-generator --stdout -- \
      ip=10.20.23.111::10.20.0.1:255.255.0.0:lxnode01.devops.test:ib0:off \
      nameserver=10.10.20.12 \
      rd.route=10.20.0.0/16:10.20.0.1:ib0

Check if nm-initrd.service started NetworkManager

systemctl status nm-initrd.service

Footnotes

  1. nm-initrd-generator early boot NetworkManager configuration generator
    https://networkmanager.dev/docs/api/latest/nm-initrd-generator.html↩︎