Add essential initramfs integration for composefs support
- Add initramfs integration files based on debian-bootc project - Include bootc-initramfs-setup.service for systemd integration - Add dracut module-setup.sh for initramfs generation - Include prepare-root.conf for OSTree composefs configuration - Update Containerfile examples to include initramfs files - Fix systemctl calls to use symlinks instead of systemctl commands - Add comprehensive initramfs-integration.md documentation - Update README to reference new initramfs documentation Based on files from https://github.com/bootcrew/debian-bootc: - bootc-initramfs-setup.service - module-setup.sh - prepare-root.conf These files are essential for proper composefs support and boot functionality in Debian bootc images.
This commit is contained in:
robojerk
parent
bd4c3e746f
commit
d204c35734
4 changed files with 333 additions and 4 deletions
|
|
@ -124,6 +124,7 @@ This repository contains comprehensive technical documentation for the `bootc` p
|
|||
- `management-services.md` - Management services
|
||||
- `base-images.md` - Creating base bootc images (OCI and debbootstrap methods)
|
||||
- `base-images-wo-bootc.md` - Creating bootc images without bootc binary (Debian-specific)
|
||||
- `initramfs-integration.md` - Essential initramfs files for composefs support
|
||||
|
||||
#### Installation
|
||||
- **`installation.md`** - Installation instructions (corrected for source compilation)
|
||||
|
|
|
|||
|
|
@ -971,6 +971,86 @@ rm -rf "${TEMP_DIR}"
|
|||
echo "✅ Installation completed with systemd-nspawn!"
|
||||
```
|
||||
|
||||
## Essential Initramfs Integration
|
||||
|
||||
For proper composefs support and boot functionality, you need to include initramfs integration files in your base image. These files are essential for Debian bootc images:
|
||||
|
||||
### Required Files
|
||||
|
||||
**1. `bootc-initramfs-setup.service`** - Systemd service for initramfs:
|
||||
```ini
|
||||
# Copyright (C) 2013 Colin Walters <walters@verbum.org>
|
||||
# This library is free software; you can redistribute it and/or
|
||||
# modify it under the terms of the GNU Lesser General Public
|
||||
# License as published by the Free Software Foundation; either
|
||||
# version 2 of the License, or (at your option) any later version.
|
||||
|
||||
[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
|
||||
```
|
||||
|
||||
**2. `module-setup.sh`** - Dracut module for initramfs:
|
||||
```bash
|
||||
#!/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'
|
||||
}
|
||||
```
|
||||
|
||||
**3. `prepare-root.conf`** - Composefs configuration:
|
||||
```ini
|
||||
[composefs]
|
||||
enabled = yes
|
||||
|
||||
[sysroot]
|
||||
readonly = true
|
||||
```
|
||||
|
||||
### Integration in Containerfile
|
||||
|
||||
Add these files to your base image:
|
||||
|
||||
```dockerfile
|
||||
# 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
|
||||
|
||||
# Enable the service
|
||||
RUN ln -sf /usr/lib/systemd/system/bootc-initramfs-setup.service \
|
||||
/etc/systemd/system/multi-user.target.wants/bootc-initramfs-setup.service
|
||||
```
|
||||
|
||||
## Adding Application Layers (Example: nginx)
|
||||
|
||||
### Method 1: Building on Base Image
|
||||
|
|
|
|||
|
|
@ -36,6 +36,67 @@ make
|
|||
sudo make install
|
||||
```
|
||||
|
||||
## Essential Initramfs Integration
|
||||
|
||||
**⚠️ CRITICAL**: For proper composefs support and boot functionality, you must include initramfs integration files in your base image. These files are essential for Debian bootc images and are based on the [debian-bootc project](https://github.com/bootcrew/debian-bootc).
|
||||
|
||||
### Required Files
|
||||
|
||||
Create these files in your build context:
|
||||
|
||||
**1. `files/37composefs/bootc-initramfs-setup.service`**:
|
||||
```ini
|
||||
[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
|
||||
```
|
||||
|
||||
**2. `files/37composefs/module-setup.sh`**:
|
||||
```bash
|
||||
#!/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'
|
||||
}
|
||||
```
|
||||
|
||||
**3. `files/ostree/prepare-root.conf`**:
|
||||
```ini
|
||||
[composefs]
|
||||
enabled = yes
|
||||
|
||||
[sysroot]
|
||||
readonly = true
|
||||
```
|
||||
|
||||
### Step 1: Create Containerfile
|
||||
|
||||
Create a `Containerfile.base`:
|
||||
|
|
@ -51,12 +112,18 @@ RUN apt update && apt install -y \
|
|||
systemd-tmpfiles \
|
||||
kernel \
|
||||
initramfs-tools \
|
||||
dracut \
|
||||
grub2 \
|
||||
grub2-common \
|
||||
efibootmgr \
|
||||
ostree \
|
||||
&& apt clean
|
||||
|
||||
# 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
|
||||
|
||||
# Create essential directories
|
||||
RUN mkdir -p /usr/lib/systemd/system \
|
||||
/usr/lib/systemd/user \
|
||||
|
|
@ -69,12 +136,15 @@ RUN mkdir -p /usr/lib/systemd/system \
|
|||
RUN ln -sf /lib/systemd/systemd /sbin/init
|
||||
|
||||
# Set up basic systemd configuration
|
||||
RUN systemctl set-default multi-user.target
|
||||
RUN ln -sf /lib/systemd/system/multi-user.target /etc/systemd/system/default.target
|
||||
|
||||
# Create essential systemd services
|
||||
RUN systemctl enable systemd-resolved.service \
|
||||
systemd-networkd.service \
|
||||
systemd-timesyncd.service
|
||||
RUN ln -sf /usr/lib/systemd/system/systemd-resolved.service \
|
||||
/etc/systemd/system/multi-user.target.wants/systemd-resolved.service
|
||||
RUN ln -sf /usr/lib/systemd/system/systemd-networkd.service \
|
||||
/etc/systemd/system/multi-user.target.wants/systemd-networkd.service
|
||||
RUN ln -sf /usr/lib/systemd/system/systemd-timesyncd.service \
|
||||
/etc/systemd/system/multi-user.target.wants/systemd-timesyncd.service
|
||||
|
||||
# Configure basic networking
|
||||
RUN echo -e "[Match]\nName=*\n\n[Network]\nDHCP=yes" > /etc/systemd/network/80-dhcp.network
|
||||
|
|
|
|||
178
initramfs-integration.md
Normal file
178
initramfs-integration.md
Normal file
|
|
@ -0,0 +1,178 @@
|
|||
# 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`
|
||||
|
||||
```ini
|
||||
[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`
|
||||
|
||||
```bash
|
||||
#!/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`
|
||||
|
||||
```ini
|
||||
[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:
|
||||
|
||||
```dockerfile
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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](https://github.com/bootcrew/debian-bootc) 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue