Enabling Two-Stage Booting with Dracut on an Existing Warewulf Image

Introduction

This article outlines the process of enabling two-stage booting using Dracut on an existing Warewulf image. Two-stage booting can be beneficial in environments where traditional single-stage booting with large image sizes causes issues due to limitations in the node's firmware or bootloader.

Problem

Traditional single-stage booting in Warewulf directly loads the entire image as an initramfs using bootloaders like iPXE or GRUB. While effective for smaller images, this approach can lead to memory management issues and boot failures when dealing with large container images.

Symptoms

You might encounter the following symptoms when trying to boot nodes with large images using single-stage booting:

• Boot failures or hangs during the initramfs loading phase.
  • You may also see a kernel panic with an error similar to not syncing: UFS: Unable to mount root fs on unknown-block(0,0)
• Error messages related to memory allocation or insufficient memory.
• Inconsistent boot behavior across different hardware.

Resolution

Enable two-stage booting with dracut on an existing Warewulf image, by following the steps below:

Prerequisites

A functional Warewulf server with an existing Rocky Linux image. If you do not already have an image available, please consult the official Warewulf Image Management documentation for guidance on creating or importing an image.

Before proceeding, we strongly recommend backing up your current image or creating a copy to use as a development version. This ensures you can easily revert to a known good state if needed.

Steps

Install the warewulf-dracut package in the image

This command uses wwctl image exec to run a command inside the specified image (rockylinux-9). The --build=false flag prevents the image from being rebuilt immediately after the command executes. Here, we install the warewulf-dracut package directly from the Warewulf GitHub releases. Replace the image name with one that matches your environment, and ensure you are using the correct version of the warewulf-dracut package. Update the URL below to point to the version you intend to use:

wwctl image exec --build=false rockylinux-9 -- /usr/bin/dnf --assumeyes install https://github.com/warewulf/warewulf/releases/download/v4.6.1/warewulf-dracut-4.6.1-1.el9.noarch.rpm

Generate the dracut initramfs inside the image

This command again uses wwctl image exec to run dracut within the image:

wwctl image exec --build=false rockylinux-9 -- /usr/bin/dracut --force --no-hostonly --add wwinit --regenerate-all

Build the Warewulf image

Build the image separately, as the previous step may take some time to complete:

wwctl image build rockylinux-9

Booting via dracut

After completing these steps, your Warewulf image is configured to support two-stage booting with dracut. You will need to configure the nodes that require two-stage booting to use the dracut iPXE or GRUB menu entry.

For iPXE:

wwctl node set <node name> --tagadd IPXEMenuEntry=dracut

For GRUB:

wwctl node set <node name> --tagadd GrubMenuEntry=dracut

You can also set this tag within a profile.

Notes

• Ensure that the version of warewulf-dracut installed in the image is the same as your Warewulf server version.
• In some cases, such as with Rocky Linux 8, you might need to remove the /etc/machine-id file within the image for Dracut to generate the initramfs correctly.
  • You can do this by running wwctl image exec <image name> -- /usr/bin/rm -f /etc/machine-id before running the dracut command. Add --build=false if you plan on building the image separately.
• The Dracut-based two-stage provisioning is considered a preview feature and may undergo changes in future Warewulf releases.

References & related articles

Warewulf Documentation - Image Management
Warewulf Documentation - Booting with Dracut
Current Warewulf Releases
Troubleshooting PXE Booting
Best Practices for Applying OS Updates Across Node Images