robojerk 526f1c1afd Initial commit: Comprehensive Debian bootc documentation

- Complete documentation for all bootc commands and subcommands
- Debian-specific adaptations and workarounds
- Manual installation methods to bypass bootc reliability issues
- Technical guides with Rust source code analysis
- Flowcharts and external command references
- Hidden command documentation (bootc internals, state, etc.)
- Composefs integration analysis
- Base image creation guides (with and without bootc binary)
- Management scripts and automation
- Comprehensive troubleshooting and examples

2025-09-15 14:02:28 -07:00

3.4 KiB

Raw Permalink Blame History

Kernel arguments

The default bootc model uses "type 1" bootloader config files stored in /boot/loader/entries, which define arguments provided to the Linux kernel.

The set of kernel arguments can be machine-specific state, but can also be managed via container updates.

The bootloader entries are currently written by the OSTree backend.

More on Linux kernel arguments: Kernel Parameters

/usr/lib/bootc/kargs.d

Many bootc use cases will use generic "OS/distribution" kernels. In order to support injecting kernel arguments, bootc supports a small custom config file format in /usr/lib/bootc/kargs.d in TOML format, that have the following structure:

[kargs]
append = ["console=ttyS0", "quiet"]
prepend = ["rd.luks.uuid=12345678-1234-1234-1234-123456789abc"]

The append and prepend arrays contain kernel arguments that will be added to the kernel command line. Arguments in prepend are added at the beginning, while append arguments are added at the end.

Local kernel argument management

It is currently undefined behavior to remove kernel arguments locally that are included in the base image via /usr/lib/bootc/kargs.d.

Injecting default arguments into custom kernels

The Linux kernel supports building in arguments into the kernel binary, at the time of this writing via the config CMDLINE build option. If you are building a custom kernel, then it often makes sense to use this instead of /usr/lib/bootc/kargs.d for example.

Debian-Specific Considerations

Debian Kernel Management

When working with Debian bootc images:

Kernel packages: Debian provides multiple kernel packages (linux-image-generic, linux-image-cloud, etc.)
Kernel headers: Install linux-headers-* packages for development
Kernel modules: Located in /lib/modules/$(uname -r)/

Example Debian Kernel Configuration

FROM debian:bookworm-slim

# Install kernel and bootc dependencies
RUN apt update && \
    apt install -y linux-image-generic linux-headers-generic bootc ostree && \
    apt clean && \
    rm -rf /var/lib/apt/lists/*

# Configure kernel arguments for Debian
COPY kargs.d/99-debian.conf /usr/lib/bootc/kargs.d/

Debian Bootloader Integration

Debian uses GRUB as the default bootloader:

GRUB configuration: /etc/default/grub
GRUB scripts: /etc/grub.d/
Update GRUB: update-grub command

Example kernel arguments configuration

Create /usr/lib/bootc/kargs.d/99-debian.conf:

[kargs]
append = [
    "console=ttyS0",
    "quiet",
    "splash",
    "systemd.show_status=false"
]
prepend = [
    "rd.luks.uuid=12345678-1234-1234-1234-123456789abc"
]

Debian Security Considerations

For Debian bootc images, consider these security-related kernel arguments:

AppArmor: apparmor=1 security=apparmor
SELinux: selinux=1 security=selinux (if using SELinux)
KASLR: kaslr (Kernel Address Space Layout Randomization)
SMEP/SMAP: nosmep nosmap (if needed for compatibility)

Hardware-Specific Arguments

Debian bootc images may need hardware-specific kernel arguments:

Virtualization: console=ttyS0 for cloud instances
Storage: root=UUID=... for specific root device
Network: net.ifnames=0 for predictable network interface names

The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.

3.4 KiB Raw Permalink Blame History