bootc-docs/initramfs-integration.md

Initramfs Integration for Debian bootc Images

This document explains the essential initramfs integration files required for proper composefs support and boot functionality in Debian bootc images.

Overview

The initramfs integration provides:

• Composefs Support: Enables composefs mounting during early boot
• Systemd Integration: Proper systemd service management in initramfs
• Dracut Module: Automatic inclusion of bootc setup in initramfs
• Configuration: OSTree and composefs configuration

Required Files

1. Systemd Service: bootc-initramfs-setup.service

Location: /usr/lib/systemd/system/bootc-initramfs-setup.service

[Unit]
DefaultDependencies=no
ConditionKernelCommandLine=composefs
ConditionPathExists=/etc/initrd-release
After=sysroot.mount
Requires=sysroot.mount
Before=initrd-root-fs.target
Before=initrd-switch-root.target
OnFailure=emergency.target
OnFailureJobMode=isolate

[Service]
Type=oneshot
ExecStart=/usr/bin/bootc-initramfs-setup
StandardInput=null
StandardOutput=journal
StandardError=journal+console
RemainAfterExit=yes

Purpose:

• Runs during initramfs boot when composefs is in kernel command line
• Executes the bootc setup script before root filesystem switch
• Handles composefs-specific initialization

2. Dracut Module: module-setup.sh

Location: /usr/lib/dracut/modules.d/37composefs/module-setup.sh

#!/usr/bin/bash
check() {
    return 0
}

depends() {
    return 0
}

install() {
    inst \
        "${moddir}/bootc-initramfs-setup" /bin/bootc-initramfs-setup
    inst \
        "${moddir}/bootc-initramfs-setup.service" \
        "${systemdsystemunitdir}/bootc-initramfs-setup.service"
    $SYSTEMCTL -q --root "${initdir}" add-wants \
        'initrd-root-fs.target' 'bootc-initramfs-setup.service'
}

Purpose:

• Dracut module that installs bootc components into initramfs
• Copies the setup script and systemd service
• Adds the service as a dependency of initrd-root-fs.target

3. OSTree Configuration: prepare-root.conf

Location: /usr/lib/ostree-boot/prepare-root.conf

[composefs]
enabled = yes

[sysroot]
readonly = true

Purpose:

• Enables composefs support in OSTree
• Sets sysroot to readonly mode for security
• Configures OSTree to use composefs for root filesystem

Integration in Containerfile

Add these files to your base image build:

# Copy initramfs integration files
COPY files/37composefs/bootc-initramfs-setup.service /usr/lib/systemd/system/
COPY files/37composefs/module-setup.sh /usr/lib/dracut/modules.d/37composefs/
COPY files/ostree/prepare-root.conf /usr/lib/ostree-boot/prepare-root.conf

# Make module-setup.sh executable
RUN chmod +x /usr/lib/dracut/modules.d/37composefs/module-setup.sh

Directory Structure

Create this directory structure in your build context:

files/
├── 37composefs/
│   ├── bootc-initramfs-setup.service
│   └── module-setup.sh
└── ostree/
    └── prepare-root.conf

Kernel Command Line Requirements

For composefs support, ensure your kernel command line includes:

composefs=sha256:...

The composefs parameter should point to the composefs image containing your root filesystem.

Dependencies

These files require:

• systemd: For service management
• dracut: For initramfs generation
• ostree: For composefs support
• bootc-initramfs-setup: The actual setup script (provided by bootc)

Testing

To test initramfs integration:

1. Build the image with initramfs files included
2. Generate initramfs using dracut
3. Boot the system with composefs kernel parameter
4. Verify that composefs mounting works correctly

Troubleshooting

Common Issues

1. Service not starting: Check that composefs is in kernel command line
2. Module not found: Ensure dracut module is in correct location
3. Permission denied: Make sure module-setup.sh is executable
4. Composefs not enabled: Verify prepare-root.conf is in correct location

Debug Commands

# Check if service is enabled
systemctl list-unit-files | grep bootc-initramfs-setup

# Verify dracut module
ls -la /usr/lib/dracut/modules.d/37composefs/

# Check composefs configuration
cat /usr/lib/ostree-boot/prepare-root.conf

# Test initramfs generation
dracut --add composefs --force

Source

These files are based on the debian-bootc project which provides Debian-specific bootc integration.

License

The files are licensed under the GNU Lesser General Public License v2.1 or later, as indicated in the copyright header.