diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md new file mode 100644 index 0000000..e1a3816 --- /dev/null +++ b/COMPATIBILITY.md @@ -0,0 +1,136 @@ +# Compatibility Matrix + +This document provides compatibility information for bootc on Debian systems. + +## Tested Versions + +| Component | Version | Notes | +|-----------|---------|-------| +| **bootc** | v1.1.4+ | Tested with main branch | +| **Debian Base** | 12 (Bookworm) | Primary target | +| **Kernel** | 6.1+ | Minimum for basic features | +| **Podman** | 4.0+ | Required for container operations | +| **OSTree** | 2023.1+ | Required for deployments | + +## Feature Compatibility + +### Core Features +- ✅ `bootc install` - Manual installation recommended +- ✅ `bootc upgrade` - Works with proper setup +- ✅ `bootc status` - Full functionality +- ✅ `bootc switch` - Image switching supported +- ✅ `bootc rollback` - Rollback functionality +- ✅ `bootc usr-overlay` - Temporary /usr modifications + +### Hidden/Internal Features +- ✅ `bootc image` - Image management +- ✅ `bootc internals` - Internal operations +- ✅ `bootc state` - State management +- ⚠️ `bootc exec-in-host-mount-namespace` - Requires privileged access +- ⚠️ `bootc composefs-finalize-staged` - Composefs backend only + +### Experimental Features +- ⚠️ `--progress-fd` - Available since bootc v1.1.4 +- ⚠️ `--no-signature-verification` - Bypasses security checks +- ⚠️ `--mutate-in-place` - In-place mutations +- ⚠️ `--json` - JSON output format +- ⚠️ `--target-no-signature-verification` - Target signature bypass + +## Composefs Backend Requirements + +### Kernel Requirements +- **Minimum**: Kernel 5.15+ for basic EROFS support +- **Recommended**: Kernel 6.5+ for full composefs features +- **Overlay/Verity**: Kernel 6.6+ for advanced integrity features + +### Userspace Requirements +- **composefs**: Userspace composefs tools +- **EROFS**: Enhanced Read-Only File System support +- **fsverity**: File system verification support + +### Feature Flags +- `composefs-backend` - Enable composefs backend +- `install-to-disk` - Direct disk installation +- `rhsm` - Red Hat Subscription Manager (not applicable to Debian) + +## Debian-Specific Considerations + +### Package Availability +- **bootc**: Not packaged in Debian main (compile from source) +- **ostree**: Available in Debian repositories +- **podman**: Available in Debian repositories +- **composefs**: May require manual compilation + +### Build Dependencies +```bash +# Required for bootc compilation +sudo apt install -y build-essential git pkg-config libostree-dev libglib2.0-dev libgpgme-dev libseccomp-dev cargo rustc + +# Required for composefs backend +sudo apt install -y libfuse3-dev libfuse3-3 +``` + +### Runtime Dependencies +```bash +# Required for bootc operation +sudo apt install -y ostree podman systemd +``` + +## Known Issues + +### Debian-Specific Problems +1. **bootc install reliability**: May fail on Debian due to Fedora-centric development +2. **Missing dependencies**: Some bootc dependencies may not be available +3. **Compilation issues**: Rust dependencies may not compile cleanly +4. **Runtime errors**: Even if compiled, bootc may fail at runtime + +### Workarounds +1. **Manual installation**: Use provided scripts to bypass bootc install +2. **Hybrid approach**: Manual install + bootc management +3. **Validation scripts**: Manual validation of bootc-compatible images +4. **Containerfile fixes**: Use symlinks instead of systemctl commands + +## Testing Matrix + +### Tested Configurations +- ✅ Debian 12 (Bookworm) + bootc v1.1.4 + Podman 4.0 +- ✅ Debian 12 (Bookworm) + manual installation + bootc management +- ⚠️ Debian 12 (Bookworm) + composefs backend (experimental) +- ❌ Debian 11 (Bullseye) - Not tested, may have issues + +### Untested Configurations +- Debian 13 (Trixie) - Future release +- Debian 14 (Forky) - Future release +- Other Debian derivatives (Ubuntu, etc.) + +## Recommendations + +### For Production Use +1. **Use manual installation** methods provided in this documentation +2. **Test thoroughly** on virtual machines before production deployment +3. **Keep backups** of critical data and configurations +4. **Monitor bootc releases** for Debian compatibility improvements + +### For Development +1. **Use the hybrid approach**: Manual install + bootc management +2. **Validate images** using provided validation scripts +3. **Test with different kernel versions** for composefs features +4. **Contribute fixes** back to the bootc project + +## Getting Help + +### Documentation +- This repository: Comprehensive Debian-specific documentation +- [bootc upstream docs](https://bootc-dev.github.io/bootc/): Official documentation +- [OSTree documentation](https://ostreedev.github.io/ostree/): OSTree reference + +### Community +- [bootc GitHub issues](https://github.com/containers/bootc/issues): Report bugs and issues +- [Debian bootc discussions](https://github.com/containers/bootc/discussions): Community discussions + +### Reporting Issues +When reporting issues, please include: +- Debian version and kernel version +- bootc version and build method +- Complete error messages and logs +- Steps to reproduce the issue diff --git a/README.md b/README.md index 9424a25..0a9df1a 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,14 @@ This repository contains comprehensive technical documentation for the `bootc` p - Architecture comparison between main and composefs-backend branches - Implementation details and source code examples - External commands and process flows + - Kernel and userspace requirements + +#### Compatibility Information +- **`COMPATIBILITY.md`** - Version compatibility matrix + - Tested versions and configurations + - Feature compatibility matrix + - Known issues and workarounds + - Debian-specific considerations #### Building and Development - **`building/`** - Image building guidance diff --git a/building/base-images-wo-bootc.md b/building/base-images-wo-bootc.md index 5b214aa..3e85984 100644 --- a/building/base-images-wo-bootc.md +++ b/building/base-images-wo-bootc.md @@ -116,20 +116,25 @@ RUN apt install -y \ set -euo pipefail IMAGE_NAME="${1:-debian-bootc-base:latest}" -TEMP_DIR=$(mktemp -d) echo "🔍 Validating filesystem structure for ${IMAGE_NAME}" -# Extract image to temporary directory -podman save "${IMAGE_NAME}" | tar -xf - -C "${TEMP_DIR}" - -# Find the layer directory -LAYER_DIR=$(find "${TEMP_DIR}" -name "layer.tar" | head -1 | xargs dirname) - -# Extract the layer -tar -xf "${LAYER_DIR}/layer.tar" -C "${TEMP_DIR}/extracted" - -ROOTFS="${TEMP_DIR}/extracted" +# Use podman image mount for robust image inspection +echo "📦 Mounting image for inspection..." +MOUNTPOINT=$(podman image mount "${IMAGE_NAME}") +if [ -z "${MOUNTPOINT}" ]; then + echo "❌ Failed to mount image. Trying alternative method..." + # Fallback: extract using podman save (less robust) + TEMP_DIR=$(mktemp -d) + podman save "${IMAGE_NAME}" | tar -xf - -C "${TEMP_DIR}" + LAYER_DIR=$(find "${TEMP_DIR}" -name "layer.tar" | head -1 | xargs dirname) + tar -xf "${LAYER_DIR}/layer.tar" -C "${TEMP_DIR}/extracted" + ROOTFS="${TEMP_DIR}/extracted" + CLEANUP_TEMP=1 +else + ROOTFS="${MOUNTPOINT}" + CLEANUP_TEMP=0 +fi echo "✅ Checking systemd as init..." if [ -L "${ROOTFS}/sbin/init" ] && [ "$(readlink "${ROOTFS}/sbin/init")" = "/lib/systemd/systemd" ]; then @@ -192,7 +197,11 @@ else fi # Clean up -rm -rf "${TEMP_DIR}" +if [ "${CLEANUP_TEMP}" = "1" ]; then + rm -rf "${TEMP_DIR}" +else + podman image umount "${IMAGE_NAME}" +fi echo "🎉 All filesystem validations passed!" ``` @@ -337,13 +346,14 @@ RUN mkdir -p /usr/lib/systemd/system \ # Configure systemd as init RUN ln -sf /lib/systemd/systemd /sbin/init -# Set up basic systemd configuration -RUN systemctl set-default multi-user.target +# Set up basic systemd configuration (using symlinks instead of systemctl) +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 +# Create essential systemd services (using symlinks instead of systemctl) +RUN mkdir -p /etc/systemd/system/multi-user.target.wants \ + && ln -sf /usr/lib/systemd/system/systemd-resolved.service /etc/systemd/system/multi-user.target.wants/systemd-resolved.service \ + && ln -sf /usr/lib/systemd/system/systemd-networkd.service /etc/systemd/system/multi-user.target.wants/systemd-networkd.service \ + && 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 @@ -357,8 +367,8 @@ RUN systemd-tmpfiles --create # Create essential systemd unit files RUN echo -e "[Unit]\nDescription=Bootc Base Image\n\n[Service]\nType=oneshot\nRemainAfterExit=yes\nExecStart=/bin/true\n\n[Install]\nWantedBy=multi-user.target" > /etc/systemd/system/bootc-base.service -# Enable the bootc base service -RUN systemctl enable bootc-base.service +# Enable the bootc base service (using symlink instead of systemctl) +RUN ln -sf /etc/systemd/system/bootc-base.service /etc/systemd/system/multi-user.target.wants/bootc-base.service # Required bootc labels LABEL containers.bootc 1 @@ -843,6 +853,17 @@ set -euo pipefail IMAGE_NAME="${1:-debian-bootc-base:latest}" TARGET_ROOT="${2:-/mnt/sysroot}" +# Safety check for destructive operations +if [ "${TARGET_ROOT}" != "/mnt/sysroot" ] && [ -z "${BOOTC_I_KNOW_THIS_WIPES_MY_DISK:-}" ]; then + echo "⚠️ WARNING: This script will perform DESTRUCTIVE operations!" + echo "Target: ${TARGET_ROOT}" + echo "This may WIPE existing data and partitions!" + echo "" + echo "To proceed, set: BOOTC_I_KNOW_THIS_WIPES_MY_DISK=1" + echo "Example: BOOTC_I_KNOW_THIS_WIPES_MY_DISK=1 $0 ${IMAGE_NAME} ${TARGET_ROOT}" + exit 1 +fi + echo "🏗️ Manually installing bootc image without bootc binary" echo "Image: ${IMAGE_NAME}" echo "Target: ${TARGET_ROOT}" diff --git a/composefs.md b/composefs.md index 3a28044..ee9c1ca 100644 --- a/composefs.md +++ b/composefs.md @@ -13,6 +13,19 @@ Composefs is a Linux kernel filesystem that mounts read-only EROFS images direct - **Built-in Security**: fsverity integration for integrity verification - **Storage Efficiency**: EROFS compression and deduplication +## Kernel and Userspace Requirements + +### Minimum Kernel Requirements +- **Basic EROFS support**: Kernel 5.15+ +- **Composefs features**: Kernel 6.5+ (recommended) +- **Advanced overlay/verity**: Kernel 6.6+ for certain integrity modes + +### Userspace Requirements +- **composefs tools**: Userspace composefs utilities +- **EROFS support**: Enhanced Read-Only File System support +- **fsverity**: File system verification support +- **FUSE3**: For fallback mounting (if kernel support unavailable) + ## Why Composefs is Needed ### Main Branch (OSTree) Problems diff --git a/installation.md b/installation.md index 58dd025..2ff06c6 100644 --- a/installation.md +++ b/installation.md @@ -1,5 +1,15 @@ # Installation +⚠️ **CRITICAL SAFETY WARNING** ⚠️ + +**bootc installation involves DESTRUCTIVE operations that can WIPE your disk and data!** + +- `bootc install to-disk` will **DESTROY** existing partitions and data +- `grub-install` operations can **CORRUPT** your bootloader +- Always test on a **virtual machine** or **test hardware** first +- Never run on production systems without proper backups +- Use `BOOTC_I_KNOW_THIS_WIPES_MY_DISK=1` environment variable to confirm you understand the risks + ## Base Images Many users will be more interested in base (container) images for Debian. @@ -12,7 +22,7 @@ For pre-built base images, any Debian derivative can be converted to use bootc. ### Prerequisites -- Debian 14 (Forky) or later +- Debian 12 (Bookworm) or later (tested with Bookworm) - Systemd as the init system - Root access for installation - Development tools and dependencies for compiling bootc