BOOTC-INITRAMFS(7)

💖 bootc-initramfs — managing the initramfs after installation 💖

okay bestie, this is bootc-initramfs(7) from the Miscellaneous Information Manual, and it's literally all about what happens to your initramfs after you've installed. buckle up 🎀

---

✨ NAME ✨

bootc-initramfs — Managing the initramfs after installation

---

🌸 DESCRIPTION 🌸

So here's the vibe: the initramfs is part of the container image, and it gets updated right along with the image. they're a package deal, no separating them 💅

On systems using the OSTree backend with a split kernel and initramfs, the canonical path is:

/usr/lib/modules/$kver/initramfs.img

and no, you can NOT just go edit the copy in /boot. that is not supported 🚫 because bootc replaces it from the container image during an update. your edits would simply get clapped. gone. periodt.

If you wanna know how to modify and regenerate the initramfs inside an image build — including dracut drop-in configuration — go read your operating system's documentation. for example, Fedora's bootc initramfs guide: https://docs.fedoraproject.org/en-US/bootc/initramfs/ 📖✨

🦋 Prefer generic configuration 🦋

not me about to say something iconic: content that at first looks machine-specific often... does not need to be?? 😭

A single generic image can carry configuration that dispatches on a machine-specific identifier at runtime — think a hardware MAC address, a DMI property, a disk serial, and so on. a udev rule that matches particular hardware, for instance, can totally ship in the base image or a shared derived image and still only act on the machine that actually has that hardware. it's giving "one outfit, many occasions" 💃

Reach for a machine-local image only when the content genuinely cannot be expressed generically. Keeping configuration in shared images means fewer distinct images to build, test, and update. slay, that's efficiency 💖

🎀 Machine-local initramfs content 🎀

okay but sometimes machine-specific initramfs content really is required — like a udev rule you need to unlock local storage that can't be selected generically. and until bootc has a dedicated interface for this use case, here's the move: build a machine-local derived image containing the configuration AND its regenerated initramfs. this keeps the image, rather than mutable files in /boot, as the source of truth. the way that's so much cleaner 🫶

⚠️ This procedure applies to the OSTree backend with a split kernel and initramfs. It does not apply to sealed composefs/UKI images.

Step one: create a build context containing the machine-specific files. for example:

.
├── Containerfile
└── 98-storage.rules

The Containerfile derives from the image shown by bootc status, adds the files, and regenerates the initramfs. Configure dracut with a drop-in under /usr/lib/dracut/dracut.conf.d and regenerate for the image's kernel, per your OS's initramfs documentation:

FROM quay.io/example/example-bootc:latest

COPY 98-storage.rules /etc/udev/rules.d/98-storage.rules
RUN echo 'install_items+=" /etc/udev/rules.d/98-storage.rules "' \
      > /usr/lib/dracut/dracut.conf.d/50-storage.conf

RUN set -xe; kver=$(ls /usr/lib/modules); \
    env DRACUT_NO_XATTR=1 dracut -vf "/usr/lib/modules/${kver}/initramfs.img" "$kver"; \
    bootc container lint

okay important facts, bestie, don't skip these 📝:

• A bootc image must contain exactly one kernel, so ls /usr/lib/modules must resolve to a single directory. bootc container lint checks this image invariant. one kernel. one. 👑
• Dracut must be told the kernel version explicitly, because its default targets the running kernel, which is not what a build should use. lowkey a trap 🙈
• The exact dracut modules and arguments depend on the base image and the content being added.

Build the image locally and deploy it exactly as any other local build. see Booting local builds (see bootc-local-builds(7)) for building against the booted image, the containers-storage transport, and automating the rebuild. And rebuild + switch to this derived image whenever either the base image or the machine-specific configuration changes. it's a two-for-one trigger, no cap 💜

🔥 The rpm-ostree client-side initramfs mechanism 🔥

On rpm-ostree-managed systems, rpm-ostree initramfs --enable enables client-side initramfs regeneration and accepts additional dracut arguments.

However — and this is the plot twist 😭 — this mechanism predates bootc and records the regenerated initramfs as a local rpm-ostree modification in the deployment origin (a regenerate-initramfs key under [rpmostree]).

Bootc does not currently know how to reproduce or carry that configuration onto a new container-image deployment. it marks a deployment with rpm-ostree local modifications as incompatible, and bootc upgrade refuses to update it with an error such as:

Deployment contains local rpm-ostree modifications

Running rpm-ostree reset removes the local modifications and allows bootc to manage the deployment again — but it also removes the client-side initramfs configuration. 😬 and it may remove other rpm-ostree package layering and overrides as well, so inspect the pending changes before running it. fr fr, look before you leap.

💀 Therefore: do not use rpm-ostree initramfs --enable for this workflow if the system is intended to continue receiving updates through bootc. use a derived container image instead.

See also Relationship with rpm-ostree (see bootc-relationships(7)).

🌈 Future direction 🌈

⭐ UKI add-ons ⭐

UKI add-ons — https://uapi-group.org/specifications/specs/unified_kernel_image/#addon-uki-format — are the intended mechanism for adding machine-specific kernel arguments or initrd content without rebuilding a Unified Kernel Image. The bootc project is working toward this model for composefs/UKI systems. main character energy, honestly 👑

For OSTree environments that do not use composefs with sealed UKIs, support for supplementary initrds has been requested in ostree#3634 — https://github.com/ostreedev/ostree/issues/3634 — and a general bootc interface is being designed in bootc#2414 — https://github.com/bootc-dev/bootc/issues/2414. Until that design is implemented, use the machine-local derived-image workflow above. that's the moment, that's the move 🧚

---

🌟 SEE ALSO 🌟

• bootc(8)
• bootc-docs(7)
• bootc-local-builds(7)
• bootc-relationships(7)

---

💐 VERSION 💐

v1.17.1

---

aaaand that's a wrap bestie 🎀 this was bootc-initramfs(7) from the Miscellaneous Information Manual, version v1.17.1 — you now know more about initramfs than like 97% of people, obsessed with you honestly 💖✨🦋 go forth and build that derived image, mwah 💅