bootc-docs/lint/quick-reference.md

bootc container lint - Quick Reference

Command Syntax

bootc container lint [OPTIONS...]

Common Options

Option	Description	Example
--rootfs	Specify root filesystem path	--rootfs /path/to/rootfs
--fatal-warnings	Treat warnings as fatal errors	--fatal-warnings
--list	List all available lints	--list
--skip	Skip specific lints	--skip var-log --skip buildah-injected
--no-truncate	Show full output (no truncation)	--no-truncate

Fatal Lints (Must Pass)

Lint	Purpose	Fix
var-run	/var/run must be symlink to /run	ln -sf /run /var/run
etc-usretc	Only /etc OR /usr/etc (not both)	rm -rf /usr/etc
bootc-kargs	Valid kernel args in /usr/lib/bootc/kargs.d/	Fix TOML syntax
kernel	Exactly one kernel in /usr/lib/modules/	rm -rf /usr/lib/modules/5.4.0
utf8	All filenames must be UTF-8	Rename non-UTF-8 files
api-base-directories	Required dirs: /dev, /proc, /sys, /run, /tmp, /var	mkdir -p /dev /proc /sys /run /tmp /var
baseimage-root	Required: /sysroot, /ostree -> sysroot/ostree	mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree

Warning Lints (Recommended)

Lint	Purpose	Fix
buildah-injected	No empty /etc/hostname or /etc/resolv.conf	rm /etc/hostname /etc/resolv.conf
baseimage-composefs	Enable composefs in ostree	echo '[composefs]\nenabled = true' > /usr/lib/ostree/prepare-root.conf
var-log	No log files in /var/log	rm -rf /var/log/*
var-tmpfiles	/var content needs tmpfiles.d entries	Create /usr/lib/tmpfiles.d/*.conf
sysusers	Users/groups need sysusers.d entries	Create /usr/lib/sysusers.d/*.conf
nonempty-boot	/boot should be empty	rm -rf /boot/*

Quick Fixes

Fix Common Issues

# Fix /var/run
rm -rf /var/run && ln -sf /run /var/run

# Fix /usr/etc
rm -rf /usr/etc

# Fix /boot
rm -rf /boot/* && mkdir -p /boot

# Fix log files
rm -rf /var/log/*

# Fix empty files
rm -f /etc/hostname /etc/resolv.conf

Create Required Structure

# API directories
mkdir -p /dev /proc /sys /run /tmp /var

# bootc structure
mkdir -p /sysroot/ostree
ln -sf sysroot/ostree /ostree

# Kernel structure
mkdir -p /usr/lib/modules/6.1.0
echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz

# Empty /boot
mkdir -p /boot

Dockerfile Examples

Minimal Working Container

FROM debian:bookworm-slim

# Install bootc
RUN apt update && apt install -y bootc && apt clean

# Fix common issues
RUN rm -rf /var/run && ln -sf /run /var/run
RUN rm -rf /usr/etc
RUN rm -rf /boot/* && mkdir -p /boot
RUN rm -rf /var/log/*

# Create required structure
RUN mkdir -p /dev /proc /sys /run /tmp /var
RUN mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree
RUN mkdir -p /usr/lib/modules/6.1.0
RUN echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz

# Lint
RUN bootc container lint --fatal-warnings

Complete bootc Image

FROM debian:bookworm-slim

# Install dependencies
RUN apt update && \
    apt install -y bootc ostree systemd && \
    apt clean && \
    rm -rf /var/lib/apt/lists/*

# Fix common issues
RUN rm -rf /var/run && ln -sf /run /var/run
RUN rm -rf /usr/etc
RUN rm -rf /boot/* && mkdir -p /boot
RUN rm -rf /var/log/*

# Create required structure
RUN mkdir -p /dev /proc /sys /run /tmp /var
RUN mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree
RUN mkdir -p /usr/lib/modules/6.1.0
RUN echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz

# Configure composefs
RUN mkdir -p /usr/lib/ostree && \
    echo '[composefs]\nenabled = true' > /usr/lib/ostree/prepare-root.conf

# Configure kernel args
RUN mkdir -p /usr/lib/bootc/kargs.d && \
    echo '[kargs]\nappend = ["console=ttyS0", "quiet"]' > /usr/lib/bootc/kargs.d/99-console.toml

# Lint
RUN bootc container lint --fatal-warnings

CI/CD Integration

GitHub Actions

- name: Lint bootc container
  run: podman run --rm ${{ matrix.image }} bootc container lint --fatal-warnings

GitLab CI

lint:
  script:
    - podman run --rm $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA bootc container lint --fatal-warnings

Jenkins

stage('Lint') {
    steps {
        sh 'podman run --rm my-image bootc container lint --fatal-warnings'
    }
}

Common Commands

# Basic lint
bootc container lint

# Lint with warnings as fatal
bootc container lint --fatal-warnings

# Lint specific rootfs
bootc container lint --rootfs /path/to/rootfs

# Skip specific lints
bootc container lint --skip var-log --skip buildah-injected

# Show all issues
bootc container lint --no-truncate

# List available lints
bootc container lint --list

# Debug mode
RUST_LOG=debug bootc container lint

Troubleshooting

Common Errors

Error	Cause	Fix
Not a symlink: var/run	/var/run is directory	ln -sf /run /var/run
Found /usr/etc	Both /etc and /usr/etc exist	rm -rf /usr/etc
Multiple kernels found	Multiple kernel versions	Keep only one
Found non-utf8 filename	Non-UTF-8 filenames	Rename files
Missing API filesystem base directory	Missing required dirs	mkdir -p /dev /proc /sys /run /tmp /var

Debug Commands

# Check container structure
podman run --rm -it my-image bash
ls -la /var/run
ls -la /etc /usr/etc
ls -la /usr/lib/modules/
ls -la /boot

# Test specific lints
bootc container lint --skip utf8 --skip var-log

# Show full output
bootc container lint --no-truncate

Best Practices

1. Run lint early in build process
2. Use --fatal-warnings in CI/CD
3. Fix issues immediately when found
4. Test with actual bootc installation
5. Use minimal base images
6. Clean up package caches
7. Avoid creating log files
8. Use symlinks for /var/run

File Locations

Purpose	Location
Kernel args	/usr/lib/bootc/kargs.d/*.toml
Composefs config	/usr/lib/ostree/prepare-root.conf
Sysusers config	/usr/lib/sysusers.d/*.conf
Tmpfiles config	/usr/lib/tmpfiles.d/*.conf
Kernel files	/usr/lib/modules/$kver/vmlinuz
Initramfs	/usr/lib/modules/$kver/initramfs.img