526f1c1afd
- 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
243 lines
6.3 KiB
Markdown
243 lines
6.3 KiB
Markdown
# bootc container lint - Quick Reference
|
|
|
|
## Command Syntax
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```dockerfile
|
|
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
|
|
|
|
```dockerfile
|
|
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
|
|
|
|
```yaml
|
|
- name: Lint bootc container
|
|
run: podman run --rm ${{ matrix.image }} bootc container lint --fatal-warnings
|
|
```
|
|
|
|
### GitLab CI
|
|
|
|
```yaml
|
|
lint:
|
|
script:
|
|
- podman run --rm $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA bootc container lint --fatal-warnings
|
|
```
|
|
|
|
### Jenkins
|
|
|
|
```groovy
|
|
stage('Lint') {
|
|
steps {
|
|
sh 'podman run --rm my-image bootc container lint --fatal-warnings'
|
|
}
|
|
}
|
|
```
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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` |
|