commit 526f1c1afd648aebd771949673c0f2f558de1ad7 Author: robojerk Date: Mon Sep 15 14:02:28 2025 -0700 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 diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..8830ec0 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "bootc"] + path = bootc + url = https://github.com/containers/bootc.git diff --git a/README.md b/README.md new file mode 100644 index 0000000..9424a25 --- /dev/null +++ b/README.md @@ -0,0 +1,270 @@ +# Debian bootc Documentation + +This repository contains comprehensive technical documentation for the `bootc` project, specifically tailored for Debian systems. The documentation covers all aspects of bootc functionality, from basic usage to advanced technical implementation details. + +## Overview + +`bootc` is a tool for managing bootable container images using OCI/Docker container images as a transport and delivery format for base OS updates. It provides transactional, in-place operating system updates using container images. **The bootc binary does not actually make bootc images.** + +## Documentation Structure + +### Core Commands + +#### Installation +- **`install/`** - Complete installation system documentation + - `technical-installation-guide.md` - Comprehensive technical guide + - `installation-flowchart.md` - Process flowcharts + - `external-commands-reference.md` - External command dependencies + - `source-code-analysis.md` - Rust source code analysis + +#### Container Operations +- **`lint/`** - Container image validation + - `bootc-lint-guide.md` - User guide + - `technical-reference.md` - Technical implementation + - `examples-and-troubleshooting.md` - Practical examples + - `quick-reference.md` - Quick reference + +- **`upgrade/`** - System updates + - `bootc-upgrade-guide.md` - User guide + - `technical-reference.md` - Technical implementation + - `examples-and-troubleshooting.md` - Practical examples + - `quick-reference.md` - Quick reference + - `external-commands-reference.md` - External commands + +#### System Management +- **`edit/`** - Declarative configuration management + - `bootc-edit-technical-guide.md` - Technical guide + - `bootc-edit-flowchart.md` - Process flowchart + - `bootc-edit-external-commands.md` - External commands + +- **`switch/`** - Image switching + - `bootc-switch-technical-guide.md` - Technical guide + - `bootc-switch-flowchart.md` - Process flowchart + - `bootc-switch-external-commands.md` - External commands + +- **`rollback/`** - System rollback + - `bootc-rollback-technical-guide.md` - Technical guide + - `bootc-rollback-flowchart.md` - Process flowchart + - `bootc-rollback-external-commands.md` - External commands + +- **`status/`** - System status + - `bootc-status-technical-guide.md` - Technical guide + - `bootc-status-flowchart.md` - Process flowchart + - `bootc-status-external-commands.md` - External commands + +- **`usr-overlay/`** - Temporary /usr modifications + - `bootc-usr-overlay-technical-guide.md` - Technical guide + - `bootc-usr-overlay-flowchart.md` - Process flowchart + - `bootc-usr-overlay-external-commands.md` - External commands + +### Hidden/Internal Commands + +#### Image Management +- **`image/`** - Container image operations + - `bootc-image-technical-guide.md` - Technical guide + - `bootc-image-flowchart.md` - Process flowchart + - `bootc-image-external-commands.md` - External commands + +#### Internal Operations +- **`internals/`** - Internal system operations + - `bootc-internals-technical-guide.md` - Technical guide + - `bootc-internals-flowchart.md` - Process flowcharts + - `bootc-internals-external-commands.md` - External commands + - `bootc-internals-architecture.md` - System architecture + - `bootc-internals-examples-troubleshooting.md` - Examples and troubleshooting + - `bootc-internals-quick-reference.md` - Quick reference + +#### State Management +- **`state/`** - System state operations + - `bootc-state-technical-guide.md` - Technical guide + - `bootc-state-flowchart.md` - Process flowchart + - `bootc-state-external-commands.md` - External commands + - `bootc-state-examples-troubleshooting.md` - Examples and troubleshooting + - `bootc-state-quick-reference.md` - Quick reference + +#### Namespace Operations +- **`exec-in-host-mount-namespace/`** - Host namespace execution + - `bootc-exec-in-host-mount-namespace-technical-guide.md` - Technical guide + - `bootc-exec-in-host-mount-namespace-flowchart.md` - Process flowchart + - `bootc-exec-in-host-mount-namespace-external-commands.md` - External commands + - `bootc-exec-in-host-mount-namespace-examples-troubleshooting.md` - Examples and troubleshooting + - `bootc-exec-in-host-mount-namespace-quick-reference.md` - Quick reference + +#### Composefs Backend +- **`composefs-finalize-staged/`** - Composefs deployment finalization + - `bootc-composefs-finalize-staged-technical-guide.md` - Technical guide + - `bootc-composefs-finalize-staged-flowchart.md` - Process flowchart + - `bootc-composefs-finalize-staged-external-commands.md` - External commands + - `bootc-composefs-finalize-staged-examples-troubleshooting.md` - Examples and troubleshooting + - `bootc-composefs-finalize-staged-quick-reference.md` - Quick reference + +### Specialized Documentation + +#### Composefs Integration +- **`composefs.md`** - Technical report on composefs integration + - Architecture comparison between main and composefs-backend branches + - Implementation details and source code examples + - External commands and process flows + +#### Building and Development +- **`building/`** - Image building guidance + - `guidance.md` - Building guidance (corrected for /usr/etc handling) + - `bootc-runtime.md` - Runtime configuration + - `users-and-groups.md` - User and group management + - `kernel-arguments.md` - Kernel argument management + - `secrets.md` - Secret management + - `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) + +#### Installation +- **`installation.md`** - Installation instructions (corrected for source compilation) + +## Key Features + +### Comprehensive Coverage +- **All Commands**: Every bootc command and subcommand documented +- **Technical Depth**: Rust source code analysis and implementation details +- **Practical Focus**: Real-world examples and troubleshooting guides +- **Debian-Specific**: Adapted for Debian package management and conventions + +### Hidden Functionality Discovered +- **Hidden Commands**: `bootc image`, `bootc internals`, `bootc state`, `bootc exec-in-host-mount-namespace` +- **Hidden Options**: `--progress-fd`, `--no-signature-verification`, `--mutate-in-place`, `--json`, `--target-no-signature-verification` +- **Feature Flags**: `composefs-backend`, `install-to-disk`, `rhsm`, `docgen` +- **Composefs Commands**: `bootc composefs-finalize-staged` (composefs-backend branch only) + +### Advanced Features +- **Anaconda Integration**: Special support for Anaconda installer environments +- **Supermin Workarounds**: Container environment compatibility fixes +- **Buildah Integration**: Container build system integration +- **RHSM Support**: Red Hat Subscription Manager integration (feature flag) +- **Documentation Generation**: CLI structure dumping for documentation (feature flag) +- **Manual Installation**: Bypass bootc installation issues on Debian +- **Hybrid Management**: Manual installation + bootc management operations +- **Composefs Backend**: Alternative filesystem backend with EROFS support + +## Technical Insights + +### Architecture +- **OSTree Backend**: Primary backend using OSTree for deployments +- **Composefs Backend**: Alternative backend using EROFS and composefs +- **Container Integration**: Full OCI/Docker container image support +- **Transactional Updates**: Atomic, rollback-capable system updates + +### Security +- **AppArmor Support**: Debian-specific security labeling +- **Signature Verification**: Container image signature validation +- **Sandboxing**: Systemd service sandboxing for security +- **Namespace Isolation**: Mount namespace operations for container safety + +### Performance +- **EROFS Integration**: Efficient compressed filesystem for composefs backend +- **Delta Updates**: Efficient update mechanisms +- **Caching**: Image and metadata caching for performance +- **Parallel Operations**: Concurrent processing where possible + +## Usage + +### Installation +```bash +# Install build dependencies +sudo apt update +sudo apt install -y build-essential git pkg-config libostree-dev libglib2.0-dev libgpgme-dev libseccomp-dev + +# Install runtime dependencies +sudo apt install -y ostree podman + +# Clone and build bootc +git clone https://github.com/containers/bootc.git +cd bootc +make +sudo make install +``` + +### Basic Usage +```bash +# Check system status +bootc status + +# Install from container image +bootc install to-filesystem quay.io/myorg/myimage:latest + +# Update system +bootc upgrade + +# Switch to different image +bootc switch quay.io/myorg/newimage:latest +``` + +### Debian-Specific Workarounds + +#### Manual Installation (Recommended for Debian) +```bash +# Build bootc-compatible image without bootc binary +./build-bootc-base-wo-bootc.sh + +# Install manually to filesystem +./install-bootc-manual.sh debian-bootc-base:latest /mnt/sysroot + +# Install bootc for management operations +./install-bootc-for-management.sh + +# Use bootc for upgrades and management +./bootc-manage.sh status +./bootc-manage.sh upgrade +``` + +#### Adding Application Layers +```bash +# Build nginx layer on base image +podman build -f examples/nginx/Containerfile -t debian-bootc-nginx:latest . + +# Install with nginx layer +./build-and-install-nginx.sh /mnt/sysroot + +# Test the installation +./test-nginx-layer.sh debian-bootc-nginx:latest +``` + +## Debian-Specific Considerations + +### Why This Documentation Exists +- **bootc Reliability Issues**: bootc may be unreliable on Debian due to Fedora-centric development +- **Missing Dependencies**: Some bootc dependencies may not be available in Debian +- **Compilation Issues**: Rust dependencies may not compile cleanly on Debian +- **Runtime Errors**: Even if compiled, bootc may fail at runtime on Debian systems + +### Our Solution +- **Manual Installation**: Bypass bootc installation issues with manual filesystem setup +- **Hybrid Approach**: Manual installation + bootc management for best of both worlds +- **Validation Scripts**: Manual validation of bootc-compatible images +- **Complete Workflows**: Ready-to-use scripts for common operations + +### Key Files for Debian Users +- `building/base-images-wo-bootc.md` - Complete guide for creating bootc images without bootc binary +- `building/base-images.md` - Standard methods for creating base images +- All command documentation includes Debian-specific adaptations + +## Contributing + +This documentation is maintained alongside the bootc project. When contributing: + +1. Ensure all commands and options are documented +2. Include technical implementation details +3. Provide practical examples and troubleshooting +4. Maintain Debian-specific adaptations +5. Update flowcharts and external command references +6. Test manual installation workflows on Debian +7. Validate that workarounds actually work + +## License + +This documentation follows the same license as the bootc project. + +## References + +- [bootc GitHub Repository](https://github.com/containers/bootc) +- [OSTree Documentation](https://ostreedev.github.io/ostree/) +- [Composefs Documentation](https://github.com/containers/composefs) +- [Debian Documentation](https://www.debian.org/doc/) \ No newline at end of file diff --git a/bootc b/bootc new file mode 160000 index 0000000..8ac9eae --- /dev/null +++ b/bootc @@ -0,0 +1 @@ +Subproject commit 8ac9eae698b74aa26dbc3e62cf9d34749d2e70e3 diff --git a/building/base-images-wo-bootc.md b/building/base-images-wo-bootc.md new file mode 100644 index 0000000..5b214aa --- /dev/null +++ b/building/base-images-wo-bootc.md @@ -0,0 +1,1162 @@ +# Create bootc base images without bootc + +The bootc binary is unreliable under Debian as it's mainly developed for Fedora despite it aiming to be a distro agnostic tool. + +In this doc we'll go over all the little things a base bootc needs to be considered a true bootc image. + +## Why Avoid bootc Binary on Debian + +### Common Issues +- **Missing Dependencies**: bootc may have Fedora-specific dependencies not available in Debian +- **Compilation Issues**: Rust dependencies may not compile cleanly on Debian +- **Runtime Errors**: Even if compiled, bootc may fail at runtime on Debian systems +- **Feature Gaps**: Some bootc features may not work properly on Debian + +### Alternative Validation +Instead of relying on `bootc container lint`, we'll manually validate our images against the bootc specification. + +## Essential Requirements for bootc Images + +### 1. Required Labels + +Every bootc image must have these labels: + +```dockerfile +LABEL containers.bootc 1 +LABEL ostree.bootable 1 +``` + +### 2. Systemd as Init System + +bootc requires systemd as the init system: + +```dockerfile +# Install systemd +RUN apt update && apt install -y systemd + +# Set systemd as init +RUN ln -sf /lib/systemd/systemd /sbin/init + +# Set default target +RUN systemctl set-default multi-user.target +``` + +### 3. Essential Systemd Services + +Enable these core systemd services: + +```dockerfile +# Enable essential services +RUN systemctl enable systemd-resolved.service +RUN systemctl enable systemd-networkd.service +RUN systemctl enable systemd-timesyncd.service +RUN systemctl enable systemd-journald.service +``` + +### 4. Proper Directory Structure + +Create essential systemd directories: + +```dockerfile +# Create systemd directories +RUN mkdir -p /usr/lib/systemd/system \ + /usr/lib/systemd/user \ + /etc/systemd/system \ + /etc/systemd/user \ + /var/lib/systemd \ + /run/systemd \ + /etc/systemd/network +``` + +### 5. Kernel and Initramfs + +Install kernel and initramfs tools: + +```dockerfile +# Install kernel and initramfs +RUN apt install -y \ + linux-image-amd64 \ + initramfs-tools \ + linux-base +``` + +### 6. Bootloader Support + +Install bootloader tools: + +```dockerfile +# Install GRUB2 +RUN apt install -y \ + grub2 \ + grub2-common \ + grub-pc-bin \ + grub-efi-amd64-bin \ + efibootmgr +``` + +### 7. OSTree Support + +Install OSTree for transactional updates: + +```dockerfile +# Install OSTree +RUN apt install -y \ + ostree \ + libostree-1-1 +``` + +## Manual Validation Checklist + +### Filesystem Structure Validation + +```bash +#!/bin/bash +# validate-filesystem.sh - Manual filesystem validation + +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" + +echo "โœ… Checking systemd as init..." +if [ -L "${ROOTFS}/sbin/init" ] && [ "$(readlink "${ROOTFS}/sbin/init")" = "/lib/systemd/systemd" ]; then + echo "โœ… systemd is properly set as init" +else + echo "โŒ systemd is not set as init" + exit 1 +fi + +echo "โœ… Checking systemd directories..." +for dir in /usr/lib/systemd/system /usr/lib/systemd/user /etc/systemd/system /etc/systemd/user; do + if [ -d "${ROOTFS}${dir}" ]; then + echo "โœ… ${dir} exists" + else + echo "โŒ ${dir} missing" + exit 1 + fi +done + +echo "โœ… Checking essential binaries..." +for binary in /lib/systemd/systemd /usr/bin/systemctl /sbin/init; do + if [ -f "${ROOTFS}${binary}" ]; then + echo "โœ… ${binary} exists" + else + echo "โŒ ${binary} missing" + exit 1 + fi +done + +echo "โœ… Checking kernel..." +if [ -d "${ROOTFS}/boot" ] && [ -f "${ROOTFS}/boot/vmlinuz-"* ]; then + echo "โœ… Kernel found" +else + echo "โŒ Kernel missing" + exit 1 +fi + +echo "โœ… Checking initramfs..." +if [ -f "${ROOTFS}/boot/initrd.img-"* ]; then + echo "โœ… Initramfs found" +else + echo "โŒ Initramfs missing" + exit 1 +fi + +echo "โœ… Checking GRUB..." +if [ -f "${ROOTFS}/usr/bin/grub-install" ] && [ -f "${ROOTFS}/usr/bin/grub-mkconfig" ]; then + echo "โœ… GRUB2 found" +else + echo "โŒ GRUB2 missing" + exit 1 +fi + +echo "โœ… Checking OSTree..." +if [ -f "${ROOTFS}/usr/bin/ostree" ]; then + echo "โœ… OSTree found" +else + echo "โŒ OSTree missing" + exit 1 +fi + +# Clean up +rm -rf "${TEMP_DIR}" + +echo "๐ŸŽ‰ All filesystem validations passed!" +``` + +### Label Validation + +```bash +#!/bin/bash +# validate-labels.sh - Validate OCI labels + +set -euo pipefail + +IMAGE_NAME="${1:-debian-bootc-base:latest}" + +echo "๐Ÿ” Validating OCI labels for ${IMAGE_NAME}" + +# Check for required labels +if podman inspect "${IMAGE_NAME}" | grep -q '"containers.bootc": "1"'; then + echo "โœ… containers.bootc label found" +else + echo "โŒ containers.bootc label missing" + exit 1 +fi + +if podman inspect "${IMAGE_NAME}" | grep -q '"ostree.bootable": "1"'; then + echo "โœ… ostree.bootable label found" +else + echo "โŒ ostree.bootable label missing" + exit 1 +fi + +echo "๐ŸŽ‰ All label validations passed!" +``` + +### Systemd Service Validation + +```bash +#!/bin/bash +# validate-systemd.sh - Validate systemd configuration + +set -euo pipefail + +IMAGE_NAME="${1:-debian-bootc-base:latest}" +TEMP_DIR=$(mktemp -d) + +echo "๐Ÿ” Validating systemd configuration for ${IMAGE_NAME}" + +# Extract and run systemd validation +podman run --rm -v "${TEMP_DIR}:/tmp" "${IMAGE_NAME}" /bin/bash -c " + echo 'Checking systemd version...' + systemctl --version + + echo 'Checking enabled services...' + systemctl list-unit-files --state=enabled | grep -E '(systemd-resolved|systemd-networkd|systemd-timesyncd)' + + echo 'Checking systemd directories...' + ls -la /usr/lib/systemd/system/ | head -5 + ls -la /etc/systemd/system/ | head -5 + + echo 'Checking network configuration...' + ls -la /etc/systemd/network/ + + echo 'Checking journal configuration...' + ls -la /var/log/journal/ || echo 'No journal directory (normal for base image)' +" + +rm -rf "${TEMP_DIR}" + +echo "๐ŸŽ‰ Systemd validation completed!" +``` + +## Complete Build Script Without bootc + +```bash +#!/bin/bash +# build-bootc-base-wo-bootc.sh - Build bootc base without bootc binary + +set -euo pipefail + +IMAGE_NAME="debian-bootc-base" +TAG="${1:-latest}" + +echo "๐Ÿ—๏ธ Building Debian bootc Base Image (without bootc binary)" +echo "Image: ${IMAGE_NAME}:${TAG}" + +# Build the image +echo "๐Ÿ“ฆ Building container image..." +podman build -f Containerfile.wo-bootc -t "${IMAGE_NAME}:${TAG}" . + +echo "โœ… Base image built successfully!" + +# Run validations +echo "๐Ÿ” Running validations..." +./validate-labels.sh "${IMAGE_NAME}:${TAG}" +./validate-filesystem.sh "${IMAGE_NAME}:${TAG}" +./validate-systemd.sh "${IMAGE_NAME}:${TAG}" + +echo "๐Ÿ“Š Image Information:" +podman images "${IMAGE_NAME}:${TAG}" + +echo "" +echo "๐Ÿš€ Ready to build application layers!" +echo "Example: podman build -f examples/nginx/Containerfile -t ${IMAGE_NAME}:nginx" +``` + +## Containerfile Without bootc Dependency + +```dockerfile +# Containerfile.wo-bootc - Build bootc base without bootc binary + +FROM debian:bookworm-slim + +# Install essential packages for bootc +RUN apt update && apt install -y \ + systemd \ + systemd-sysusers \ + systemd-tmpfiles \ + systemd-resolved \ + systemd-networkd \ + systemd-timesyncd \ + kernel \ + initramfs-tools \ + linux-base \ + grub2 \ + grub2-common \ + grub-pc-bin \ + grub-efi-amd64-bin \ + efibootmgr \ + ostree \ + libostree-1-1 \ + && apt clean + +# Create essential directories +RUN mkdir -p /usr/lib/systemd/system \ + /usr/lib/systemd/user \ + /etc/systemd/system \ + /etc/systemd/user \ + /var/lib/systemd \ + /run/systemd \ + /etc/systemd/network + +# Configure systemd as init +RUN ln -sf /lib/systemd/systemd /sbin/init + +# Set up basic systemd configuration +RUN systemctl set-default multi-user.target + +# Create essential systemd services +RUN systemctl enable systemd-resolved.service \ + systemd-networkd.service \ + systemd-timesyncd.service + +# Configure basic networking +RUN echo -e "[Match]\nName=*\n\n[Network]\nDHCP=yes" > /etc/systemd/network/80-dhcp.network + +# Set up basic users and groups +RUN systemd-sysusers --create + +# Configure tmpfiles +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 + +# Required bootc labels +LABEL containers.bootc 1 +LABEL ostree.bootable 1 + +# Set default command +CMD ["/lib/systemd/systemd"] +``` + +## Advanced Validation Scripts + +### Network Configuration Validation + +```bash +#!/bin/bash +# validate-network.sh - Validate network configuration + +set -euo pipefail + +IMAGE_NAME="${1:-debian-bootc-base:latest}" + +echo "๐Ÿ” Validating network configuration for ${IMAGE_NAME}" + +podman run --rm "${IMAGE_NAME}" /bin/bash -c " + echo 'Checking systemd-networkd configuration...' + if [ -f /etc/systemd/network/80-dhcp.network ]; then + echo 'โœ… DHCP network configuration found' + cat /etc/systemd/network/80-dhcp.network + else + echo 'โŒ DHCP network configuration missing' + exit 1 + fi + + echo 'Checking systemd-resolved configuration...' + if [ -f /etc/systemd/resolved.conf ]; then + echo 'โœ… systemd-resolved configuration found' + else + echo 'โŒ systemd-resolved configuration missing' + exit 1 + fi +" + +echo "๐ŸŽ‰ Network validation completed!" +``` + +### Bootloader Validation + +```bash +#!/bin/bash +# validate-bootloader.sh - Validate bootloader configuration + +set -euo pipefail + +IMAGE_NAME="${1:-debian-bootc-base:latest}" + +echo "๐Ÿ” Validating bootloader configuration for ${IMAGE_NAME}" + +podman run --rm "${IMAGE_NAME}" /bin/bash -c " + echo 'Checking GRUB2 installation...' + if command -v grub-install >/dev/null 2>&1; then + echo 'โœ… grub-install found' + grub-install --version + else + echo 'โŒ grub-install missing' + exit 1 + fi + + if command -v grub-mkconfig >/dev/null 2>&1; then + echo 'โœ… grub-mkconfig found' + grub-mkconfig --version + else + echo 'โŒ grub-mkconfig missing' + exit 1 + fi + + echo 'Checking EFI support...' + if command -v efibootmgr >/dev/null 2>&1; then + echo 'โœ… efibootmgr found' + efibootmgr --version + else + echo 'โŒ efibootmgr missing' + exit 1 + fi +" + +echo "๐ŸŽ‰ Bootloader validation completed!" +``` + +## Complete Validation Suite + +```bash +#!/bin/bash +# validate-all.sh - Complete validation suite + +set -euo pipefail + +IMAGE_NAME="${1:-debian-bootc-base:latest}" + +echo "๐Ÿ” Running complete validation suite for ${IMAGE_NAME}" +echo "==================================================" + +# Run all validations +./validate-labels.sh "${IMAGE_NAME}" +echo "" + +./validate-filesystem.sh "${IMAGE_NAME}" +echo "" + +./validate-systemd.sh "${IMAGE_NAME}" +echo "" + +./validate-network.sh "${IMAGE_NAME}" +echo "" + +./validate-bootloader.sh "${IMAGE_NAME}" +echo "" + +echo "๐ŸŽ‰ All validations passed! Image is bootc-compatible." +echo "Image: ${IMAGE_NAME}" +echo "Ready for deployment with bootc!" +``` + +## Troubleshooting Common Issues + +### Missing systemd Services +```bash +# Check if services are properly enabled +podman run --rm debian-bootc-base:latest systemctl list-unit-files --state=enabled +``` + +### Kernel Issues +```bash +# Check kernel installation +podman run --rm debian-bootc-base:latest ls -la /boot/ +``` + +### GRUB Issues +```bash +# Check GRUB installation +podman run --rm debian-bootc-base:latest which grub-install +``` + +### OSTree Issues +```bash +# Check OSTree installation +podman run --rm debian-bootc-base:latest ostree --version +``` + +## Installing bootc for Management Operations + +While bootc may be unreliable for installation on Debian, you can still install it for management operations like upgrades, rollbacks, and status checking. + +### Installing bootc from Source + +```bash +#!/bin/bash +# install-bootc-for-management.sh - Install bootc for management only + +set -euo pipefail + +echo "๐Ÿ—๏ธ Installing bootc for management operations on Debian" + +# Install build dependencies +echo "๐Ÿ“ฆ Installing build dependencies..." +sudo apt update && sudo apt install -y \ + build-essential \ + git \ + pkg-config \ + libostree-dev \ + libglib2.0-dev \ + libgpgme-dev \ + libseccomp-dev \ + cargo \ + rustc + +# Install runtime dependencies +echo "๐Ÿ“ฆ Installing runtime dependencies..." +sudo apt install -y \ + ostree \ + podman \ + systemd + +# Clone and build bootc +echo "๐Ÿ”จ Building bootc from source..." +if [ ! -d "bootc" ]; then + git clone https://github.com/containers/bootc.git +fi + +cd bootc +git fetch origin +git checkout origin/main + +# Build bootc +echo "๐Ÿ”จ Compiling bootc..." +make + +# Install bootc +echo "๐Ÿ“ฆ Installing bootc..." +sudo make install + +# Verify installation +echo "โœ… Verifying installation..." +bootc --version + +echo "๐ŸŽ‰ bootc installed for management operations!" +echo "Note: Use manual installation for deploying images" +``` + +### Installing bootc with Composefs Support + +```bash +#!/bin/bash +# install-bootc-composefs.sh - Install bootc with composefs support + +set -euo pipefail + +echo "๐Ÿ—๏ธ Installing bootc with composefs support for management" + +# Install additional dependencies for composefs +echo "๐Ÿ“ฆ Installing composefs dependencies..." +sudo apt update && sudo apt install -y \ + build-essential \ + git \ + pkg-config \ + libostree-dev \ + libglib2.0-dev \ + libgpgme-dev \ + libseccomp-dev \ + cargo \ + rustc \ + libfuse3-dev \ + libfuse3-3 + +# Clone and build bootc with composefs +echo "๐Ÿ”จ Building bootc with composefs support..." +if [ ! -d "bootc" ]; then + git clone https://github.com/containers/bootc.git +fi + +cd bootc +git fetch origin +git checkout origin/composefs-backend + +# Build with composefs feature +echo "๐Ÿ”จ Compiling bootc with composefs..." +cargo build --release --features composefs-backend + +# Install bootc +echo "๐Ÿ“ฆ Installing bootc..." +sudo cp target/release/bootc /usr/local/bin/ +sudo chmod +x /usr/local/bin/bootc + +# Verify installation +echo "โœ… Verifying installation..." +bootc --version + +echo "๐ŸŽ‰ bootc with composefs support installed!" +``` + +### Management Operations with bootc + +Once bootc is installed, you can use it for management operations: + +```bash +#!/bin/bash +# bootc-management-examples.sh - Examples of bootc management operations + +set -euo pipefail + +echo "๐Ÿ”ง bootc Management Operations Examples" + +# Check system status +echo "๐Ÿ“Š Checking system status..." +bootc status + +# Check for upgrades +echo "๐Ÿ”„ Checking for upgrades..." +bootc upgrade --check + +# Apply upgrades (if available) +echo "โฌ†๏ธ Applying upgrades..." +bootc upgrade --apply + +# Switch to different image +echo "๐Ÿ”„ Switching image..." +# bootc switch quay.io/myorg/myapp:latest --apply + +# Rollback if needed +echo "โช Rolling back..." +# bootc rollback --apply + +# Check usr-overlay status +echo "๐Ÿ“ Checking usr-overlay..." +bootc usr-overlay + +echo "โœ… Management operations completed!" +``` + +### Hybrid Approach: Manual Install + bootc Management + +```bash +#!/bin/bash +# hybrid-bootc-workflow.sh - Manual install + bootc management + +set -euo pipefail + +IMAGE_NAME="${1:-debian-bootc-nginx:latest}" +TARGET_ROOT="${2:-/mnt/sysroot}" + +echo "๐Ÿ”„ Hybrid bootc workflow: Manual install + bootc management" +echo "Image: ${IMAGE_NAME}" +echo "Target: ${TARGET_ROOT}" + +# Step 1: Manual installation (reliable) +echo "๐Ÿ“ฆ Step 1: Manual installation..." +./install-bootc-manual.sh "${IMAGE_NAME}" "${TARGET_ROOT}" + +# Step 2: Install bootc for management +echo "๐Ÿ”ง Step 2: Installing bootc for management..." +./install-bootc-for-management.sh + +# Step 3: Initialize bootc management +echo "โš™๏ธ Step 3: Initializing bootc management..." +sudo chroot "${TARGET_ROOT}" bootc status || echo "bootc status not available yet" + +# Step 4: Set up bootc configuration +echo "๐Ÿ“ Step 4: Setting up bootc configuration..." +sudo chroot "${TARGET_ROOT}" /bin/bash -c " + # Create bootc configuration + mkdir -p /etc/bootc + echo 'image: ${IMAGE_NAME}' > /etc/bootc/config.yaml + echo 'boot_order: [\"current\", \"rollback\"]' >> /etc/bootc/config.yaml +" + +echo "โœ… Hybrid workflow completed!" +echo "Manual installation: โœ…" +echo "bootc management: โœ…" +echo "Ready for upgrades and management!" +``` + +### bootc Management Service + +```bash +#!/bin/bash +# setup-bootc-management-service.sh - Set up bootc management service + +set -euo pipefail + +echo "๐Ÿ”ง Setting up bootc management service" + +# Create systemd service for bootc management +sudo tee /etc/systemd/system/bootc-management.service > /dev/null << 'EOF' +[Unit] +Description=bootc Management Service +Documentation=man:bootc(1) +After=network.target + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStart=/usr/local/bin/bootc status +ExecReload=/usr/local/bin/bootc upgrade --check +StandardOutput=journal +StandardError=journal + +[Install] +WantedBy=multi-user.target +EOF + +# Create bootc upgrade timer +sudo tee /etc/systemd/system/bootc-upgrade.timer > /dev/null << 'EOF' +[Unit] +Description=Run bootc upgrade check daily +Requires=bootc-management.service + +[Timer] +OnCalendar=daily +Persistent=true + +[Install] +WantedBy=timers.target +EOF + +# Create bootc upgrade service +sudo tee /etc/systemd/system/bootc-upgrade.service > /dev/null << 'EOF' +[Unit] +Description=bootc Upgrade Service +Documentation=man:bootc(1) +After=network.target + +[Service] +Type=oneshot +ExecStart=/usr/local/bin/bootc upgrade --check +StandardOutput=journal +StandardError=journal +EOF + +# Enable services +sudo systemctl daemon-reload +sudo systemctl enable bootc-management.service +sudo systemctl enable bootc-upgrade.timer + +echo "โœ… bootc management services configured!" +echo "Status: systemctl status bootc-management" +echo "Upgrades: systemctl status bootc-upgrade.timer" +``` + +### Management Scripts + +```bash +#!/bin/bash +# bootc-manage.sh - Comprehensive bootc management script + +set -euo pipefail + +ACTION="${1:-status}" +IMAGE_NAME="${2:-}" + +case "${ACTION}" in + "status") + echo "๐Ÿ“Š bootc System Status" + bootc status + ;; + "check-upgrades") + echo "๐Ÿ”„ Checking for upgrades..." + bootc upgrade --check + ;; + "upgrade") + echo "โฌ†๏ธ Applying upgrades..." + bootc upgrade --apply + ;; + "switch") + if [ -z "${IMAGE_NAME}" ]; then + echo "โŒ Error: Image name required for switch" + echo "Usage: $0 switch " + exit 1 + fi + echo "๐Ÿ”„ Switching to ${IMAGE_NAME}..." + bootc switch "${IMAGE_NAME}" --apply + ;; + "rollback") + echo "โช Rolling back..." + bootc rollback --apply + ;; + "usr-overlay") + echo "๐Ÿ“ Managing usr-overlay..." + bootc usr-overlay + ;; + "help") + echo "๐Ÿ”ง bootc Management Script" + echo "Usage: $0 [image-name]" + echo "" + echo "Actions:" + echo " status - Show system status" + echo " check-upgrades - Check for available upgrades" + echo " upgrade - Apply upgrades" + echo " switch - Switch to different image" + echo " rollback - Rollback to previous version" + echo " usr-overlay - Manage usr-overlay" + echo " help - Show this help" + ;; + *) + echo "โŒ Unknown action: ${ACTION}" + echo "Run '$0 help' for usage information" + exit 1 + ;; +esac +``` + +## Bypassing bootc for Installation + +Since bootc may be unreliable on Debian, you can manually install your bootc-compatible images to the filesystem without using the `bootc install` command. + +### Manual Installation Process + +```bash +#!/bin/bash +# install-bootc-manual.sh - Manually install bootc image without bootc binary + +set -euo pipefail + +IMAGE_NAME="${1:-debian-bootc-base:latest}" +TARGET_ROOT="${2:-/mnt/sysroot}" + +echo "๐Ÿ—๏ธ Manually installing bootc image without bootc binary" +echo "Image: ${IMAGE_NAME}" +echo "Target: ${TARGET_ROOT}" + +# Create target directory +sudo mkdir -p "${TARGET_ROOT}" + +# Extract image to temporary directory +TEMP_DIR=$(mktemp -d) +echo "๐Ÿ“ฆ Extracting image to ${TEMP_DIR}..." + +# Save and extract image +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 to target +echo "๐Ÿ“‚ Extracting filesystem to ${TARGET_ROOT}..." +sudo tar -xf "${LAYER_DIR}/layer.tar" -C "${TARGET_ROOT}" + +# Set up essential directories +echo "โš™๏ธ Setting up essential directories..." +sudo mkdir -p "${TARGET_ROOT}/boot" +sudo mkdir -p "${TARGET_ROOT}/sysroot" +sudo mkdir -p "${TARGET_ROOT}/var/lib/ostree" + +# Set up bind mounts for chroot +echo "๐Ÿ”— Setting up bind mounts..." +sudo mount --bind /proc "${TARGET_ROOT}/proc" +sudo mount --bind /sys "${TARGET_ROOT}/sys" +sudo mount --bind /dev "${TARGET_ROOT}/dev" + +# Configure systemd in chroot +echo "๐Ÿ”ง Configuring systemd..." +sudo chroot "${TARGET_ROOT}" systemctl set-default multi-user.target + +# Generate initramfs +echo "๐Ÿš€ Generating initramfs..." +sudo chroot "${TARGET_ROOT}" update-initramfs -u + +# Install GRUB (if installing to disk) +if [ "${TARGET_ROOT}" != "/mnt/sysroot" ]; then + echo "๐Ÿ’พ Installing GRUB..." + sudo chroot "${TARGET_ROOT}" grub-install /dev/sda + sudo chroot "${TARGET_ROOT}" grub-mkconfig -o /boot/grub/grub.cfg +fi + +# Clean up +sudo umount "${TARGET_ROOT}/proc" || true +sudo umount "${TARGET_ROOT}/sys" || true +sudo umount "${TARGET_ROOT}/dev" || true +rm -rf "${TEMP_DIR}" + +echo "โœ… Manual installation completed!" +echo "Target: ${TARGET_ROOT}" +``` + +### Alternative: Using systemd-nspawn + +```bash +#!/bin/bash +# install-bootc-nspawn.sh - Install using systemd-nspawn + +set -euo pipefail + +IMAGE_NAME="${1:-debian-bootc-base:latest}" +TARGET_ROOT="${2:-/mnt/sysroot}" + +echo "๐Ÿ—๏ธ Installing bootc image using systemd-nspawn" +echo "Image: ${IMAGE_NAME}" +echo "Target: ${TARGET_ROOT}" + +# Extract image first +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) +sudo tar -xf "${LAYER_DIR}/layer.tar" -C "${TARGET_ROOT}" + +# Use systemd-nspawn for configuration +echo "๐Ÿ”ง Configuring with systemd-nspawn..." +sudo systemd-nspawn -D "${TARGET_ROOT}" /bin/bash -c " + systemctl set-default multi-user.target + update-initramfs -u + systemctl enable systemd-resolved.service + systemctl enable systemd-networkd.service +" + +rm -rf "${TEMP_DIR}" +echo "โœ… Installation completed with systemd-nspawn!" +``` + +## Adding Application Layers (Example: nginx) + +### Method 1: Building on Base Image + +```dockerfile +# examples/nginx/Containerfile +FROM debian-bootc-base:latest + +# Install nginx +RUN apt update && apt install -y nginx && apt clean + +# Configure nginx +RUN echo 'server { \ + listen 80; \ + server_name _; \ + location / { \ + return 200 "Hello from bootc nginx!"; \ + add_header Content-Type text/plain; \ + } \ +}' > /etc/nginx/sites-available/default + +RUN ln -sf /etc/nginx/sites-available/default /etc/nginx/sites-enabled/ +RUN rm -f /etc/nginx/sites-enabled/default.bak + +# Enable nginx service +RUN systemctl enable nginx.service + +# Create nginx user and group +RUN systemd-sysusers --create + +# Required bootc labels +LABEL containers.bootc 1 +LABEL ostree.bootable 1 + +# Set default command +CMD ["/lib/systemd/systemd"] +``` + +### Method 2: Multi-stage Build + +```dockerfile +# examples/nginx/Containerfile.multistage +FROM debian:bookworm-slim as base + +# Install base packages +RUN apt update && apt install -y \ + systemd \ + systemd-sysusers \ + systemd-tmpfiles \ + systemd-resolved \ + systemd-networkd \ + systemd-timesyncd \ + kernel \ + initramfs-tools \ + grub2 \ + grub2-common \ + efibootmgr \ + ostree \ + nginx \ + && apt clean + +# Configure systemd +RUN ln -sf /lib/systemd/systemd /sbin/init +RUN systemctl set-default multi-user.target +RUN systemctl enable systemd-resolved.service \ + systemd-networkd.service \ + systemd-timesyncd.service \ + nginx.service + +# Configure nginx +RUN echo 'server { \ + listen 80; \ + server_name _; \ + location / { \ + return 200 "Hello from bootc nginx!"; \ + add_header Content-Type text/plain; \ + } \ +}' > /etc/nginx/sites-available/default + +RUN ln -sf /etc/nginx/sites-available/default /etc/nginx/sites-enabled/ +RUN rm -f /etc/nginx/sites-enabled/default.bak + +# Create essential directories +RUN mkdir -p /usr/lib/systemd/system \ + /usr/lib/systemd/user \ + /etc/systemd/system \ + /etc/systemd/user \ + /var/lib/systemd \ + /run/systemd \ + /etc/systemd/network + +# Configure networking +RUN echo -e "[Match]\nName=*\n\n[Network]\nDHCP=yes" > /etc/systemd/network/80-dhcp.network + +# Set up users and groups +RUN systemd-sysusers --create +RUN systemd-tmpfiles --create + +# Required bootc labels +LABEL containers.bootc 1 +LABEL ostree.bootable 1 + +# Set default command +CMD ["/lib/systemd/systemd"] +``` + +### Build and Install Script + +```bash +#!/bin/bash +# build-and-install-nginx.sh - Build nginx layer and install manually + +set -euo pipefail + +BASE_IMAGE="debian-bootc-base:latest" +NGINX_IMAGE="debian-bootc-nginx:latest" +TARGET_ROOT="${1:-/mnt/sysroot}" + +echo "๐Ÿ—๏ธ Building nginx layer on bootc base" +echo "Base: ${BASE_IMAGE}" +echo "Nginx: ${NGINX_IMAGE}" +echo "Target: ${TARGET_ROOT}" + +# Build nginx image +echo "๐Ÿ“ฆ Building nginx image..." +podman build -f examples/nginx/Containerfile -t "${NGINX_IMAGE}" . + +# Validate the image +echo "๐Ÿ” Validating nginx image..." +./validate-all.sh "${NGINX_IMAGE}" + +# Install manually +echo "๐Ÿ’พ Installing nginx image..." +./install-bootc-manual.sh "${NGINX_IMAGE}" "${TARGET_ROOT}" + +echo "โœ… nginx bootc image built and installed!" +echo "Image: ${NGINX_IMAGE}" +echo "Target: ${TARGET_ROOT}" +``` + +### Testing the nginx Layer + +```bash +#!/bin/bash +# test-nginx-layer.sh - Test nginx layer + +set -euo pipefail + +NGINX_IMAGE="${1:-debian-bootc-nginx:latest}" + +echo "๐Ÿงช Testing nginx layer: ${NGINX_IMAGE}" + +# Test nginx configuration +echo "๐Ÿ” Testing nginx configuration..." +podman run --rm "${NGINX_IMAGE}" nginx -t + +# Test systemd services +echo "๐Ÿ” Testing systemd services..." +podman run --rm "${NGINX_IMAGE}" systemctl list-unit-files --state=enabled | grep nginx + +# Test nginx startup +echo "๐Ÿ” Testing nginx startup..." +podman run --rm "${NGINX_IMAGE}" systemctl is-enabled nginx.service + +# Test HTTP response (if possible) +echo "๐Ÿ” Testing HTTP response..." +podman run --rm -d --name nginx-test -p 8080:80 "${NGINX_IMAGE}" +sleep 5 + +if curl -s http://localhost:8080 | grep -q "Hello from bootc nginx"; then + echo "โœ… nginx HTTP response test passed" +else + echo "โŒ nginx HTTP response test failed" +fi + +podman stop nginx-test +podman rm nginx-test + +echo "๐ŸŽ‰ nginx layer testing completed!" +``` + +### Complete Project Structure with nginx + +``` +debian-bootc-project/ +โ”œโ”€โ”€ build-bootc-base-wo-bootc.sh # Build base image +โ”œโ”€โ”€ build-and-install-nginx.sh # Build and install nginx +โ”œโ”€โ”€ install-bootc-manual.sh # Manual installation +โ”œโ”€โ”€ install-bootc-nspawn.sh # nspawn installation +โ”œโ”€โ”€ validate-all.sh # Complete validation +โ”œโ”€โ”€ test-nginx-layer.sh # Test nginx layer +โ”œโ”€โ”€ Containerfile.wo-bootc # Base image containerfile +โ”œโ”€โ”€ examples/ +โ”‚ โ””โ”€โ”€ nginx/ +โ”‚ โ”œโ”€โ”€ Containerfile # nginx layer +โ”‚ โ””โ”€โ”€ Containerfile.multistage # Multi-stage nginx +โ””โ”€โ”€ scripts/ + โ”œโ”€โ”€ validate-filesystem.sh + โ”œโ”€โ”€ validate-labels.sh + โ”œโ”€โ”€ validate-systemd.sh + โ”œโ”€โ”€ validate-network.sh + โ””โ”€โ”€ validate-bootloader.sh +``` + +### Usage Workflow + +```bash +# 1. Build base image +./build-bootc-base-wo-bootc.sh + +# 2. Build and install nginx layer +./build-and-install-nginx.sh /mnt/sysroot + +# 3. Test the installation +./test-nginx-layer.sh debian-bootc-nginx:latest + +# 4. Boot the system (if installed to disk) +# Reboot and select the new boot entry +``` + +## Summary + +This approach allows you to create fully bootc-compatible base images on Debian without relying on the potentially unreliable bootc binary. The manual validation scripts ensure your images meet all bootc requirements, making them ready for deployment and management with bootc once it's properly working on your system. + +The key is understanding what bootc expects and manually validating those requirements rather than depending on the bootc binary for validation. You can also manually install these images without using `bootc install`, and easily add application layers like nginx on top of your base images. \ No newline at end of file diff --git a/building/base-images.md b/building/base-images.md new file mode 100644 index 0000000..565ca63 --- /dev/null +++ b/building/base-images.md @@ -0,0 +1,471 @@ +# Building Base bootc Images + +This document provides detailed instructions for creating base bootc images using two different approaches: + +1. **Method 1**: Building from an existing OCI image +2. **Method 2**: Building from scratch using debootstrap/mmdebstrap + +## Important Note + +**bootc does not create base images** - it only deploys and manages them. Base image creation requires separate tools and processes as described below. + +## Method 1: Building from Existing OCI Image + +This method takes an existing Debian OCI image and converts it into a bootc-compatible base image. + +### Prerequisites + +```bash +# Install required tools +sudo apt update +sudo apt install -y podman buildah skopeo + +# Install bootc for validation +git clone https://github.com/containers/bootc.git +cd bootc +make +sudo make install +``` + +### Step 1: Create Containerfile + +Create a `Containerfile.base`: + +```dockerfile +# Containerfile.base - Convert existing Debian image to bootc base +FROM debian:bookworm-slim + +# Install essential packages for bootc +RUN apt update && apt install -y \ + systemd \ + systemd-sysusers \ + systemd-tmpfiles \ + kernel \ + initramfs-tools \ + grub2 \ + grub2-common \ + efibootmgr \ + ostree \ + && apt clean + +# Create essential directories +RUN mkdir -p /usr/lib/systemd/system \ + /usr/lib/systemd/user \ + /etc/systemd/system \ + /etc/systemd/user \ + /var/lib/systemd \ + /run/systemd + +# Configure systemd as init +RUN ln -sf /lib/systemd/systemd /sbin/init + +# Set up basic systemd configuration +RUN systemctl set-default multi-user.target + +# Create essential systemd services +RUN systemctl enable systemd-resolved.service \ + systemd-networkd.service \ + systemd-timesyncd.service + +# Configure basic networking +RUN echo -e "[Match]\nName=*\n\n[Network]\nDHCP=yes" > /etc/systemd/network/80-dhcp.network + +# Set up basic users and groups +RUN systemd-sysusers --root=/ --create + +# Configure tmpfiles +RUN systemd-tmpfiles --create --root=/ + +# Install bootc (for validation) +COPY --from=quay.io/containers/bootc:latest /usr/bin/bootc /usr/bin/bootc + +# Validate the image +RUN bootc container lint + +# Required bootc labels +LABEL containers.bootc 1 +LABEL ostree.bootable 1 + +# Set default command +CMD ["/lib/systemd/systemd"] +``` + +### Step 2: Build the Base Image + +```bash +#!/bin/bash +# build-base-from-existing.sh + +set -euo pipefail + +IMAGE_NAME="debian-bootc-base" +TAG="${1:-latest}" + +echo "๐Ÿ—๏ธ Building Debian bootc Base Image from Existing OCI" +echo "Image: ${IMAGE_NAME}:${TAG}" + +# Build the base image +echo "๐Ÿ“ฆ Building container image..." +podman build -f Containerfile.base -t "${IMAGE_NAME}:${TAG}" . + +echo "โœ… Base image built successfully!" +echo "Image: ${IMAGE_NAME}:${TAG}" + +# Show image info +echo "" +echo "๐Ÿ“Š Image Information:" +podman images "${IMAGE_NAME}:${TAG}" + +echo "" +echo "๐Ÿš€ Ready to build application layers!" +echo "Example: podman build -f examples/nginx/Containerfile -t ${IMAGE_NAME}:nginx" +``` + +### Step 3: Test the Base Image + +```bash +# Test the base image +podman run --rm -it debian-bootc-base:latest /bin/bash + +# Validate with bootc +bootc container lint debian-bootc-base:latest +``` + +## Method 2: Building from Scratch with debootstrap/mmdebstrap + +This method creates a completely custom Debian base image from scratch. + +### Prerequisites + +```bash +# Install required tools +sudo apt update +sudo apt install -y \ + debootstrap \ + mmdebstrap \ + podman \ + buildah \ + skopeo \ + qemu-user-static + +# Install bootc for validation +git clone https://github.com/containers/bootc.git +cd bootc +make +sudo make install +``` + +### Step 1: Create Root Filesystem + +Create a script to build the root filesystem: + +```bash +#!/bin/bash +# build-rootfs.sh - Build Debian rootfs from scratch + +set -euo pipefail + +ROOTFS_DIR="rootfs" +DEBIAN_RELEASE="bookworm" +ARCH="amd64" + +echo "๐Ÿ—๏ธ Building Debian Root Filesystem from Scratch" +echo "Release: ${DEBIAN_RELEASE}" +echo "Architecture: ${ARCH}" +echo "Rootfs: ${ROOTFS_DIR}/" + +# Clean up previous build +if [ -d "${ROOTFS_DIR}" ]; then + echo "๐Ÿงน Cleaning up previous build..." + sudo rm -rf "${ROOTFS_DIR}" +fi + +# Create rootfs directory +mkdir -p "${ROOTFS_DIR}" + +# Build rootfs with mmdebstrap (faster and more reliable) +echo "๐Ÿ“ฆ Building rootfs with mmdebstrap..." +sudo mmdebstrap \ + --arch="${ARCH}" \ + --variant=minbase \ + --include=systemd,systemd-sysusers,systemd-tmpfiles,kernel,initramfs-tools,grub2,grub2-common,efibootmgr,ostree \ + "${DEBIAN_RELEASE}" \ + "${ROOTFS_DIR}" \ + http://deb.debian.org/debian + +echo "โœ… Rootfs built successfully!" + +# Set up basic systemd configuration +echo "โš™๏ธ Configuring systemd..." +sudo chroot "${ROOTFS_DIR}" systemctl set-default multi-user.target + +# Create essential systemd services +sudo chroot "${ROOTFS_DIR}" systemctl enable systemd-resolved.service +sudo chroot "${ROOTFS_DIR}" systemctl enable systemd-networkd.service +sudo chroot "${ROOTFS_DIR}" systemctl enable systemd-timesyncd.service + +# Configure basic networking +sudo tee "${ROOTFS_DIR}/etc/systemd/network/80-dhcp.network" > /dev/null < /etc/nginx/sites-available/default +RUN ln -sf /etc/nginx/sites-available/default /etc/nginx/sites-enabled/ + +# Enable nginx service +RUN systemctl enable nginx.service + +# Validate the image +RUN bootc container lint + +# Required bootc labels +LABEL containers.bootc 1 +LABEL ostree.bootable 1 + +# Set default command +CMD ["/lib/systemd/systemd"] +``` + +## Complete Project Structure + +``` +debian-bootc-base/ +โ”œโ”€โ”€ build-rootfs.sh # Rootfs build script +โ”œโ”€โ”€ build-scratch-bootc.sh # Main build script +โ”œโ”€โ”€ Containerfile.base # From existing OCI image +โ”œโ”€โ”€ Containerfile.scratch # From scratch build +โ”œโ”€โ”€ rootfs/ # Generated rootfs (Method 2) +โ”œโ”€โ”€ examples/ +โ”‚ โ”œโ”€โ”€ nginx/ +โ”‚ โ”‚ โ””โ”€โ”€ Containerfile # Example nginx layer +โ”‚ โ””โ”€โ”€ apache/ +โ”‚ โ””โ”€โ”€ Containerfile # Example apache layer +โ””โ”€โ”€ README.md +``` + +## Usage Examples + +### Method 1: From Existing Image +```bash +# Build base image from existing Debian +./build-base-from-existing.sh + +# Build application layer +podman build -f examples/nginx/Containerfile -t debian-bootc-base:nginx . +``` + +### Method 2: From Scratch +```bash +# Build rootfs and base image +./build-scratch-bootc.sh + +# Build application layer +podman build -f examples/nginx/Containerfile -t debian-scratch-bootc:nginx . +``` + +## Validation and Testing + +### Validate Base Image +```bash +# Validate with bootc +bootc container lint debian-bootc-base:latest +bootc container lint debian-scratch-bootc:latest +``` + +### Test Base Image +```bash +# Test the base image +podman run --rm -it debian-bootc-base:latest /bin/bash +podman run --rm -it debian-scratch-bootc:latest /bin/bash +``` + +### Deploy with bootc +```bash +# Install to filesystem +bootc install to-filesystem debian-bootc-base:latest + +# Check status +bootc status +``` + +## Troubleshooting + +### Common Issues + +1. **Permission Errors**: Ensure scripts are executable + ```bash + chmod +x build-*.sh + ``` + +2. **Rootfs Build Fails**: Check internet connection and mirrors + ```bash + # Test mirror connectivity + curl -I http://deb.debian.org/debian/ + ``` + +3. **bootc Validation Fails**: Check required labels and systemd configuration + ```bash + # Check labels + podman inspect debian-bootc-base:latest | grep -A 10 Labels + + # Check systemd + podman run --rm debian-bootc-base:latest systemctl --version + ``` + +4. **Image Too Large**: Optimize by removing unnecessary packages + ```bash + # Clean up in rootfs + sudo chroot rootfs apt autoremove --purge -y + sudo chroot rootfs apt clean + ``` + +## Advanced Configuration + +### Custom Kernel +```bash +# Install specific kernel version +sudo chroot rootfs apt install -y linux-image-6.1.0-10-amd64 +``` + +### Custom Systemd Services +```bash +# Add custom service +sudo tee rootfs/etc/systemd/system/myapp.service > /dev/null < The original Docker container model of using "layers" to model applications has been extremely successful. This project aims to apply the same technique for bootable host systems - using standard OCI/Docker containers as a transport and delivery format for base operating system updates. + +Every tool and technique for creating application base images should apply to the host Linux OS as much as possible. + +## Understanding mutability + +When run as a container (particularly as part of a build), bootc-compatible images have all parts of the filesystem (e.g. `/usr` in particular) as fully mutable state, and writing there is encouraged (see below). + +When "deployed" to a physical or virtual machine, the container image files are read-only by default; for more, see filesystem. + +**Important**: Do not manually create `/usr/etc` directories or copy files there. The `/usr/etc` tree is generated client-side by bootc/ostree and contains the default container image's view of `/etc`. Manually putting files into this location can create undefined behavior and will cause `bootc container lint` to fail. + +## Installing software + +For Debian package management using `apt`, it is very much expected that the pattern of + +```dockerfile +RUN apt update && apt install -y somepackage && apt clean && rm -rf /var/lib/apt/lists/* +``` + +type flow Just Works here - the same way as it does for "application" container images. This pattern is really how Docker got started. + +There's not much special to this that doesn't also apply to application containers; but see below. + +### Nesting OCI containers in bootc containers + +The OCI format uses "whiteouts" represented in the tar stream as special `.wh` files, and typically consumed by the Linux kernel `overlayfs` driver as special `0:0` character devices. Without special work, whiteouts cannot be nested. + +Hence, an invocation like + +```dockerfile +RUN podman pull quay.io/exampleimage/someimage +``` + +will create problems, as the `podman` runtime will create whiteout files inside the container image filesystem itself. + +Special care and code changes will need to be made to container runtimes to support such nesting. Some more discussion in this tracker issue. + +## systemd units + +The model that is most popular with the Docker/OCI world is "microservice" style containers with the application as pid 1, isolating the applications from each other and from the host system - as opposed to "system containers" which run an init system like systemd, typically also SSH and often multiple logical "application" components as part of the same container. + +The bootc project generally expects systemd as pid 1, and if you embed software in your derived image, the default would then be that that software is initially launched via a systemd unit. + +```dockerfile +RUN apt update && apt install -y postgresql && apt clean && rm -rf /var/lib/apt/lists/* +``` + +Would typically also carry a systemd unit, and that service will be launched the same way as it would on a package-based system. + +## Users and groups + +Note that the above `postgresql` today will allocate a user; this leads to the topic of users, groups and SSH keys. + +## Configuration + +A key aspect of choosing a bootc-based operating system model is that _code_ and _configuration_ can be strictly "lifecycle bound" together in exactly the same way. + +(Today, that's by including the configuration into the base container image; however a future enhancement for bootc will also support dynamically-injected ConfigMaps, similar to kubelet) + +You can add configuration files to the same places they're expected by typical package systems on Debian - in `/usr` (preferred where possible) or `/etc`. systemd has long advocated and supported a model where `/usr` (e.g. `/usr/lib/systemd/system`) contains content owned by the operating system image. + +`/etc` is machine-local state. However, per filesystem.md it's important to note that the underlying OSTree system performs a 3-way merge of `/etc`, so changes you make in the container image to e.g. `/etc/postgresql/postgresql.conf` will be applied on update, assuming it is not modified locally. + +**Important**: When building bootc images, work with `/etc` normally during the build process. Do not manually create or manipulate `/usr/etc` - this is handled automatically by bootc/ostree during deployment. + +### Prefer using drop-in directories + +These "locally modified" files can be a source of state drift. The best pattern to use is "drop-in" directories that are merged dynamically by the relevant software. systemd supports this comprehensively; see drop-ins for example in units. + +And instead of modifying `/etc/sudoers`, it's best practice to add a file into `/etc/sudoers.d` for example. + +Not all software supports this, however; and this is why there is generic support for `/etc`. + +### Configuration in /usr vs /etc + +Some software supports generic configuration both `/usr` and `/etc` - systemd, among others. Because bootc supports _derivation_ (the way OCI containers work) - it is supported and encouraged to put configuration files in `/usr` (instead of `/etc`) where possible, because then the state is consistently immutable. + +One pattern is to replace a configuration file like `/etc/postgresql/postgresql.conf` with a symlink to e.g. `/usr/postgres/etc/postgresql.conf` for example, although this can run afoul of SELinux labeling. + +### Secrets + +There is a dedicated document for secrets, which is a special case of configuration. + +## Handling read-only vs writable locations + +The high level pattern for bootc systems is summarized again this way: + +* Put read-only data and executables in `/usr` +* Put configuration files in `/usr` (if they're static), or `/etc` if they need to be machine-local +* Put "data" (log files, databases, etc.) underneath `/var` + +However, some software installs to `/opt/examplepkg` or another location outside of `/usr`, and may include all three types of data underneath its single toplevel directory. For example, it may write log files to `/opt/examplepkg/logs`. A simple way to handle this is to change the directories that need to be writable to symbolic links to `/var`: + +```dockerfile +RUN apt update && apt install -y examplepkg && apt clean && rm -rf /var/lib/apt/lists/* && \ + mv /opt/examplepkg/logs /var/log/examplepkg && \ + ln -sr /opt/examplepkg/logs /var/log/examplepkg +``` + +The Debian bootc puppet example is one instance of this. + +Another option is to configure the systemd unit launching the service to do these mounts dynamically via e.g. + +``` +BindPaths=/var/log/exampleapp:/opt/exampleapp/logs +``` + +## Building bootc Images Correctly + +### The Right Way to Build bootc Images + +When building bootc images, follow these principles: + +1. **Work with `/etc` normally**: Configure files in `/etc` during the build process as you would in any container +2. **Don't manually create `/usr/etc`**: This directory is managed automatically by bootc/ostree +3. **Use `bootc container lint`**: Always run this to validate your image before finalizing +4. **Let bootc handle the transformation**: The `/etc` to `/usr/etc` conversion happens during deployment, not during build + +### Common Mistakes to Avoid + +- โŒ **Don't do this**: Manually creating `/usr/etc` and copying files there +- โŒ **Don't do this**: Removing `/etc` and trying to recreate it manually +- โŒ **Don't do this**: Assuming you need to handle `/etc` normalization yourself + +### Correct Build Pattern + +```dockerfile +FROM debian:bookworm-slim + +# Install packages normally +RUN apt update && apt install -y your-packages && apt clean + +# Configure /etc files normally +RUN echo "config" > /etc/myapp/config.conf +RUN systemctl enable myapp + +# Let bootc validate everything +RUN bootc container lint + +LABEL containers.bootc 1 +LABEL ostree.bootable 1 +``` + +## Debian-Specific Considerations + +### Package Management Integration + +When building Debian bootc images, consider: + +- **apt repositories**: Ensure your base image includes the necessary Debian repositories +- **Package selection**: Choose packages that are compatible with the bootc model +- **Dependencies**: Handle Debian package dependencies properly in your Dockerfile +- **Security updates**: Plan for how security updates will be handled through the bootc model + +### Debian Configuration Patterns + +- **dpkg configuration**: Use `debconf` for non-interactive package configuration +- **Service management**: Leverage Debian's systemd integration +- **User management**: Follow Debian conventions for user and group creation +- **Logging**: Use Debian's standard logging locations in `/var/log` + +### Example Dockerfile for Debian bootc + +```dockerfile +FROM debian:bookworm-slim + +# Install bootc and dependencies +RUN apt update && \ + apt install -y bootc ostree podman systemd && \ + apt clean && \ + rm -rf /var/lib/apt/lists/* + +# Install your application packages +RUN apt update && \ + apt install -y nginx postgresql && \ + apt clean && \ + rm -rf /var/lib/apt/lists/* + +# Configure services normally - bootc handles /etc automatically +RUN systemctl enable nginx postgresql + +# Configure /etc files normally - don't manually create /usr/etc +RUN echo "server_name example.com;" > /etc/nginx/conf.d/default.conf + +# Set up proper permissions and links +RUN ln -sf /var/log/nginx /usr/share/nginx/logs + +# Let bootc lint check everything is correct +RUN bootc container lint + +LABEL containers.bootc 1 +LABEL ostree.bootable 1 +``` + +--- + +The Linux Foundationยฎ (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage. diff --git a/building/kernel-arguments.md b/building/kernel-arguments.md new file mode 100644 index 0000000..a28dc87 --- /dev/null +++ b/building/kernel-arguments.md @@ -0,0 +1,101 @@ +# 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](https://docs.kernel.org/admin-guide/kernel-parameters.html) + +## /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: + +```toml +[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 + +```dockerfile +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`: + +```toml +[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. + diff --git a/building/management-services.md b/building/management-services.md new file mode 100644 index 0000000..d07e583 --- /dev/null +++ b/building/management-services.md @@ -0,0 +1,254 @@ +# Management services + +Management services in bootc systems handle operational tasks like updates, monitoring, and system maintenance. This document covers how to implement and manage these services in Debian bootc images. + +## Overview + +Management services are systemd services that handle: + +- **System updates**: Managing bootc updates and rollbacks +- **Monitoring**: Health checks and system monitoring +- **Maintenance**: Log rotation, cleanup, and maintenance tasks +- **Configuration**: Dynamic configuration updates + +## Update Management + +### bootc Update Service + +Create a service to handle bootc updates: + +```dockerfile +# Create update management service +COPY bootc-update.service /usr/lib/systemd/system/ +COPY bootc-update.timer /usr/lib/systemd/system/ +COPY update-bootc.sh /usr/local/bin/ +``` + +Service file (`/usr/lib/systemd/system/bootc-update.service`): +```ini +[Unit] +Description=Update bootc system +After=network.target + +[Service] +Type=oneshot +ExecStart=/usr/local/bin/update-bootc.sh +StandardOutput=journal +StandardError=journal +``` + +Timer file (`/usr/lib/systemd/system/bootc-update.timer`): +```ini +[Unit] +Description=Run bootc update daily +Requires=bootc-update.service + +[Timer] +OnCalendar=daily +Persistent=true + +[Install] +WantedBy=timers.target +``` + +### Update Script Example + +```bash +#!/bin/bash +# /usr/local/bin/update-bootc.sh + +set -euo pipefail + +# Check for updates +if bootc update --check; then + echo "Updates available, applying..." + bootc update + echo "Update completed successfully" +else + echo "No updates available" +fi +``` + +## Monitoring Services + +### Health Check Service + +Create a health check service: + +```dockerfile +# Create health check service +COPY health-check.service /usr/lib/systemd/system/ +COPY health-check.timer /usr/lib/systemd/system/ +COPY health-check.sh /usr/local/bin/ +``` + +Health check script example: +```bash +#!/bin/bash +# /usr/local/bin/health-check.sh + +set -euo pipefail + +# Check system health +check_system_health() { + # Check disk space + df -h | awk 'NR>1 {if ($5+0 > 80) exit 1}' + + # Check memory usage + free | awk 'NR==2{if ($3/$2 > 0.9) exit 1}' + + # Check critical services + systemctl is-active --quiet sshd || exit 1 + systemctl is-active --quiet systemd-resolved || exit 1 + + echo "System health check passed" +} + +check_system_health +``` + +### Log Management + +Set up log rotation and management: + +```dockerfile +# Configure logrotate +COPY logrotate.conf /etc/logrotate.d/bootc + +# Create log cleanup service +COPY log-cleanup.service /usr/lib/systemd/system/ +COPY log-cleanup.timer /usr/lib/systemd/system/ +COPY cleanup-logs.sh /usr/local/bin/ +``` + +## Configuration Management + +### Dynamic Configuration Updates + +Create a service for configuration updates: + +```dockerfile +# Create config management service +COPY config-manager.service /usr/lib/systemd/system/ +COPY config-manager.sh /usr/local/bin/ +COPY config-templates/ /etc/config-templates/ +``` + +### Configuration Template Example + +```bash +#!/bin/bash +# /usr/local/bin/config-manager.sh + +set -euo pipefail + +# Update configuration from templates +update_config() { + local template="$1" + local target="$2" + + # Process template with environment variables + envsubst < "$template" > "$target" + + # Reload service if needed + if systemctl is-active --quiet "$3"; then + systemctl reload "$3" + fi +} + +# Update configurations +update_config /etc/config-templates/nginx.conf /etc/nginx/nginx.conf nginx +update_config /etc/config-templates/sshd.conf /etc/ssh/sshd_config sshd +``` + +## Debian-Specific Considerations + +### Debian Service Management + +Debian uses systemd for service management: + +- **Service files**: `/usr/lib/systemd/system/` +- **User services**: `~/.config/systemd/user/` +- **Service enablement**: `systemctl enable` +- **Service status**: `systemctl status` + +### Example Debian Management Services + +```dockerfile +FROM debian:bookworm-slim + +# Install management tools +RUN apt update && \ + apt install -y curl jq logrotate cron && \ + apt clean && \ + rm -rf /var/lib/apt/lists/* + +# Create management services +COPY management-services/ /usr/lib/systemd/system/ +COPY management-scripts/ /usr/local/bin/ + +# Set up permissions +RUN chmod +x /usr/local/bin/*.sh + +# Enable services +RUN systemctl enable bootc-update.timer health-check.timer log-cleanup.timer +``` + +### Debian Package Integration + +Integrate with Debian package management: + +```bash +#!/bin/bash +# Update Debian packages alongside bootc + +# Update package lists +apt update + +# Check for security updates +apt list --upgradable | grep -i security + +# Install security updates +apt upgrade -y + +# Clean up +apt autoremove -y +apt autoclean +``` + +### Debian Monitoring Tools + +Use Debian's monitoring tools: + +- **htop**: Process monitoring +- **iotop**: I/O monitoring +- **nethogs**: Network monitoring +- **sysstat**: System statistics + +## Best Practices + +### Service Design + +1. **Idempotent operations**: Services should be safe to run multiple times +2. **Error handling**: Proper error handling and logging +3. **Resource limits**: Set appropriate resource limits +4. **Dependencies**: Define proper service dependencies + +### Security Considerations + +1. **Least privilege**: Run services with minimal required privileges +2. **Secure communication**: Use TLS for network communication +3. **Access control**: Restrict access to management interfaces +4. **Audit logging**: Log all management operations + +### Operational Guidelines + +1. **Monitoring**: Monitor service health and performance +2. **Alerting**: Set up alerts for critical failures +3. **Documentation**: Document all management services +4. **Testing**: Test management services in non-production environments + +--- + +The Linux Foundationยฎ (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage. + diff --git a/building/secrets.md b/building/secrets.md new file mode 100644 index 0000000..75670a5 --- /dev/null +++ b/building/secrets.md @@ -0,0 +1,197 @@ +# Secrets + +Managing secrets in bootc systems requires careful consideration of security and operational requirements. This document covers various approaches for handling secrets in Debian bootc images. + +## Overview + +Secrets in bootc systems can be managed through several approaches: + +- **Build-time secrets**: Embedded in the container image (not recommended for production) +- **Runtime secrets**: Injected at deployment time +- **External secret management**: Using external systems like HashiCorp Vault, Kubernetes secrets, etc. + +## Build-time Secrets (Not Recommended) + +While it's possible to embed secrets directly in the container image, this is generally not recommended for production use: + +```dockerfile +# NOT RECOMMENDED for production +RUN echo "secret-password" > /etc/myapp/password +``` + +## Runtime Secret Injection + +### systemd Credentials + +systemd provides a credentials system for securely passing secrets to services: + +```dockerfile +# Create a service that uses credentials +COPY myapp.service /usr/lib/systemd/system/ +``` + +Service file example (`/usr/lib/systemd/system/myapp.service`): +```ini +[Unit] +Description=My Application + +[Service] +ExecStart=/usr/bin/myapp +LoadCredential=password:/etc/myapp/password +LoadCredential=api-key:/etc/myapp/api-key +``` + +### cloud-init Integration + +For cloud deployments, use cloud-init to inject secrets: + +```yaml +# cloud-init configuration +#cloud-config +write_files: + - path: /etc/myapp/config + content: | + password: ${PASSWORD} + api_key: ${API_KEY} + permissions: '0600' + owner: root:root +``` + +### Environment Variables + +Use systemd environment files for secrets: + +```dockerfile +# Create environment file template +COPY myapp.env.template /usr/lib/systemd/system/myapp.env.template +``` + +## External Secret Management + +### HashiCorp Vault Integration + +Create a service that fetches secrets from Vault: + +```dockerfile +# Install Vault client +RUN apt update && \ + apt install -y vault && \ + apt clean && \ + rm -rf /var/lib/apt/lists/* + +# Create Vault service +COPY vault-fetch.service /usr/lib/systemd/system/ +COPY fetch-secrets.sh /usr/local/bin/ +``` + +### Kubernetes Secrets + +For Kubernetes deployments, use Kubernetes secrets: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: myapp-secrets +type: Opaque +data: + password: + api-key: +``` + +## Debian-Specific Considerations + +### Debian Secret Management Tools + +Debian provides several tools for secret management: + +- **gnupg**: For encryption/decryption +- **openssl**: For certificate management +- **keyutils**: For kernel keyring management + +### Example Debian Secret Management + +```dockerfile +FROM debian:bookworm-slim + +# Install secret management tools +RUN apt update && \ + apt install -y gnupg openssl keyutils && \ + apt clean && \ + rm -rf /var/lib/apt/lists/* + +# Create secret management service +COPY secret-manager.service /usr/lib/systemd/system/ +COPY secret-manager.sh /usr/local/bin/ + +# Set up proper permissions +RUN chmod 700 /usr/local/bin/secret-manager.sh +``` + +### Debian Keyring Integration + +Use Debian's keyring system for managing secrets: + +```bash +# Add secret to kernel keyring +echo "my-secret" | keyctl padd user myapp-secret @u + +# Retrieve secret in application +SECRET=$(keyctl print user:myapp-secret) +``` + +### AppArmor Considerations + +When using AppArmor with secrets: + +```dockerfile +# Create AppArmor profile for secret access +COPY usr.bin.myapp /etc/apparmor.d/ +RUN aa-enforce /etc/apparmor.d/usr.bin.myapp +``` + +## Best Practices + +### Security Guidelines + +1. **Never embed secrets in images**: Use external secret management +2. **Use least privilege**: Only grant access to secrets that are needed +3. **Rotate secrets regularly**: Implement secret rotation policies +4. **Audit secret access**: Log all secret access and usage +5. **Use encryption**: Encrypt secrets at rest and in transit + +### Operational Guidelines + +1. **Use templates**: Create secret templates that can be filled at runtime +2. **Validate secrets**: Check that secrets are valid before use +3. **Handle failures gracefully**: Plan for secret retrieval failures +4. **Monitor secret usage**: Track secret access patterns + +### Example Implementation + +```dockerfile +FROM debian:bookworm-slim + +# Install dependencies +RUN apt update && \ + apt install -y curl jq gnupg && \ + apt clean && \ + rm -rf /var/lib/apt/lists/* + +# Create secret management system +COPY secret-manager.service /usr/lib/systemd/system/ +COPY secret-manager.sh /usr/local/bin/ +COPY secret-templates/ /etc/secret-templates/ + +# Set up proper permissions +RUN chmod 700 /usr/local/bin/secret-manager.sh && \ + chmod 600 /etc/secret-templates/* + +# Enable secret manager +RUN systemctl enable secret-manager.service +``` + +--- + +The Linux Foundationยฎ (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage. + diff --git a/building/users-and-groups.md b/building/users-and-groups.md new file mode 100644 index 0000000..2189862 --- /dev/null +++ b/building/users-and-groups.md @@ -0,0 +1,222 @@ +# Users and groups + +This is one of the more complex topics. Generally speaking, bootc has nothing to do directly with configuring users or groups; it is a generic OS update/configuration mechanism. (There is currently just one small exception in that `bootc install` has a special case `--root-ssh-authorized-keys` argument, but it's very much optional). + +## Generic base images + +Commonly OS/distribution base images will be generic, i.e. without any configuration. It is _very strongly recommended_ to avoid hardcoded passwords and ssh keys with publicly-available private keys (as Vagrant does) in generic images. + +### Injecting SSH keys via systemd credentials + +The systemd project has documentation for [credentials](https://systemd.io/CREDENTIALS/) which can be used in some environments to inject a root password or SSH authorized_keys. For many cases, this is a best practice. + +At the time of this writing this relies on SMBIOS which is mainly configurable in local virtualization environments. (qemu). + +### Injecting users and SSH keys via cloud-init, etc. + +Many IaaS and virtualization systems are oriented towards a "metadata server" (see e.g. [AWS instance metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)) that are commonly processed by software such as cloud-init or Ignition or equivalent. + +The base image you're using may include such software, or you can install it in your own derived images. + +In this model, SSH configuration is managed outside of the bootable image. See e.g. [GCP oslogin](https://cloud.google.com/compute/docs/oslogin) for an example of this where operating system identities are linked to the underlying Google accounts. + +### Adding users and credentials via custom logic (container or unit) + +Of course, systems like `cloud-init` are not privileged; you can inject any logic you want to manage credentials via e.g. a systemd unit (which may launch a container image) that manages things however you prefer. Commonly, this would be a custom network-hosted source. For example, [FreeIPA](https://www.freeipa.org/). + +Another example in a Kubernetes-oriented infrastructure would be a container image that fetches desired authentication credentials from a CRD hosted in the API server. (To do things like this it's suggested to reuse the kubelet credentials) + +### System users and groups (added via packages, etc) + +It is common for packages (deb/rpm/etc) to allocate system users or groups as part of e.g `apt|dnf install ` such as Apache or MySQL, and this is often done by directly invoking `useradd` or `groupadd` as part of package pre/post installation scripts. + +With the `shadow-utils` implementation of `useradd` and the default glibc `files` this will result in changes to the traditional `/etc/passwd` and `/etc/shadow` files as part of the container build. + +#### System drift from local /etc/passwd modifications + +When the system is initially installed, the `/etc/passwd` in the container image will be applied and contain desired users. + +By default (without `etc = transient`, see below), the `/etc` directory is machine-local persistent state. If subsequently `/etc/passwd` is modified local to the machine (as is common for e.g. setting a root password) then any new changes in the container image (such as users from new packages) _will not appear_ on subsequent updates by default (they will be in `/usr/etc/passwd` instead - the default image version). + +The general best fix for this is to use `systemd-sysusers` instead of allocating a user/group at build time at all. + +##### Using systemd-sysusers + +See [systemd-sysusers](https://www.freedesktop.org/software/systemd/man/sysusers.d.html). For example in your derived build: + +```dockerfile +COPY mycustom-user.conf /usr/lib/sysusers.d +``` + +A key aspect of how this works is that `sysusers` will make changes to the traditional `/etc/passwd` file as necessary on boot instead of at build time. If `/etc` is persistent, this can avoid uid/gid drift (but in the general case it does mean that uid/gid allocation can depend on how a specific machine was upgraded over time). + +Note that the default `sysusers` design is that users are allocated on the client side (per machine). Avoid having non-root owned files managed by `sysusers` inside your image, especially underneath `/usr`. With the exception of `setuid` or `setgid` binaries (which should also be strongly avoided), there is generally no valid reason for having non-root owned files in `/usr` or other runtime-immutable directories. + +#### User and group home directories and /var + +For systems configured with persistent `/home` โ†’ `/var/home`, any changes to `/var` made in the container image after initial installation _will not be applied on subsequent updates_. If for example you inject `/var/home/someuser/.ssh/authorized_keys` into a container build, existing systems will _not_ get the updated authorized keys file. + +#### Using DynamicUser=yes for systemd units + +For "system" users it's strongly recommended to use systemd `DynamicUser=yes` where possible. + +This is significantly better than the pattern of allocating users/groups at "package install time" (e.g. [Fedora package user/group guidelines](https://docs.fedoraproject.org/en-US/packaging-guidelines/UsersAndGroups/)) because it avoids potential UID/GID drift (see below). + +#### Using systemd JSON user records + +See [JSON user records](https://systemd.io/USER_RECORD/). Unlike `sysusers`, the canonical state for these live in `/usr` - if a subsequent image drops a user record, then it will also vanish from the system - unlike `sysusers.d`. + +#### nss-altfiles + +The [nss-altfiles](https://github.com/altfiles/nss-altfiles) project (long) predates systemd JSON user records. It aims to help split "system" users into `/usr/lib/passwd` and `/usr/lib/group`. It's very important to understand that this aligns with the way the OSTree project handles the "3 way merge" for `/etc` as it relates to `/etc/passwd`. Currently, if the `/etc/passwd` file is modified in any way on the local system, then subsequent changes to `/etc/passwd` in the container image _will not be applied_. + +Some base images may have `nss-altfiles` enabled by default; this is currently the case for base images built by rpm-ostree. + +Commonly, base images will have some "system" users pre-allocated and managed via this file again to avoid uid/gid drift. + +In a derived container build, you can also append users to `/usr/lib/passwd` for example. (At the time of this writing there is no command line to do so though). + +Typically it is more preferable to use `sysusers.d` or `DynamicUser=yes`. + +### Machine-local state for users + +At this point, it is important to understand the filesystem layout - the default is up to the base image. + +The default Linux concept of a user has data stored in both `/etc` (`/etc/passwd`, `/etc/shadow` and groups) and `/home`. The choice for how these work is up to the base image, but a common default for generic base images is to have both be machine-local persistent state. In this model `/home` would be a symlink to `/var/home/someuser`. + +#### Injecting users and SSH keys via at system provisioning time + +For base images where `/etc` and `/var` are configured to persist by default, it will then be generally supported to inject users via "installers" such as Anaconda (interactively or via kickstart) or any others. + +Typically generic installers such as this are designed for "one time bootstrap" and again then the configuration becomes mutable machine-local state that can be changed "day 2" via some other mechanism. + +The simple case is a user with a password - typically the installer helps set the initial password, but to change it there is a different in-system tool (such as `passwd` or a GUI as part of Cockpit, GNOME/KDE/etc). + +It is intended that these flows work equivalently in a bootc-compatible system, to support users directly installing "generic" base images, without requiring changes to the tools above. + +#### Transient home directories + +Many operating system deployments will want to minimize persistent, mutable and executable state - and user home directories are that + +But it is also valid to default to having e.g. `/home` be a `tmpfs` to ensure user data is cleaned up across reboots (and this pairs particularly well with a transient `/etc` as well): + +In order to set up the user's home directory to e.g. inject SSH `authorized_keys` or other files, a good approach is to use systemd `tmpfiles.d` snippets: + +``` +f~ /home/someuser/.ssh/authorized_keys 600 someuser someuser - +``` + +which can be embedded in the image as `/usr/lib/tmpfiles.d/someuser-keys.conf`. + +Or a service embedded in the image can fetch keys from the network and write them; this is the pattern used by cloud-init and afterburn. + +### UID/GID drift + +Any invocation of `useradd` or `groupadd` that does not allocate a _fixed_ UID/GID may be subject to "drift" in subsequent rebuilds by default. + +One possibility is to explicitly force these user/group allocations into a static state, via `systemd-sysusers` (per above) or explicitly adding the users with static IDs _before_ a dpkg installation script operates on it: + +```dockerfile +RUN < /var/lib/composefs-transient-state/staged-deployment + +# Create staged deployment directory +mkdir -p /sysroot/composefs/staged-deployment-id + +# Create origin file +cat > /sysroot/composefs/staged-deployment-id/staged-deployment-id.origin << EOF +[origin] +container=ostree-unverified-image:quay.io/myorg/composefs:latest + +[boot] +type=uki +digest=sha256:abcd1234... +EOF + +echo "Staged deployment created" +``` + +### 3. EROFS Image Operations + +#### Mount EROFS Image + +```bash +#!/bin/bash +# Mount EROFS image for testing + +echo "=== EROFS Image Operations ===" +echo "Date: $(date)" +echo + +# Create mount point +mkdir -p /mnt/erofs + +# Mount EROFS image +echo "Mounting EROFS image..." +mount -t erofs /path/to/image.erofs /mnt/erofs + +# Check mount +echo "Mount status:" +mount | grep erofs + +# List contents +echo "EROFS contents:" +ls -la /mnt/erofs/ + +# Unmount +echo "Unmounting EROFS image..." +umount /mnt/erofs +``` + +#### Create EROFS Image + +```bash +#!/bin/bash +# Create EROFS image for testing + +echo "=== Create EROFS Image ===" +echo "Date: $(date)" +echo + +# Create source directory +mkdir -p /tmp/erofs-source/etc +mkdir -p /tmp/erofs-source/usr +mkdir -p /tmp/erofs-source/var + +# Add some test files +echo "test config" > /tmp/erofs-source/etc/test.conf +echo "test binary" > /tmp/erofs-source/usr/bin/test + +# Create EROFS image +echo "Creating EROFS image..." +mkfs.erofs -z lz4 /tmp/test-image.erofs /tmp/erofs-source + +# Verify image +echo "Verifying EROFS image..." +file /tmp/test-image.erofs + +# Clean up +rm -rf /tmp/erofs-source +``` + +### 4. Bootloader Operations + +#### GRUB Configuration + +```bash +#!/bin/bash +# GRUB configuration for composefs + +echo "=== GRUB Configuration ===" +echo "Date: $(date)" +echo + +# Check GRUB configuration +echo "Current GRUB configuration:" +cat /boot/grub/grub.cfg | grep -i composefs + +# Update GRUB configuration +echo "Updating GRUB configuration..." +grub-mkconfig -o /boot/grub/grub.cfg + +# Check GRUB entries +echo "GRUB entries:" +ls -la /boot/grub/loader/entries/ + +# Check for staged entries +echo "Staged GRUB entries:" +find /boot/grub/ -name "*.staged" -type f +``` + +#### systemd-boot Configuration + +```bash +#!/bin/bash +# systemd-boot configuration for composefs + +echo "=== systemd-boot Configuration ===" +echo "Date: $(date)" +echo + +# Check systemd-boot entries +echo "systemd-boot entries:" +bootctl list + +# Check ESP partition +echo "ESP partition:" +ls -la /boot/efi/EFI/ + +# Check for staged entries +echo "Staged systemd-boot entries:" +find /boot/efi/ -name "*.staged" -type f + +# Update boot entries +echo "Updating boot entries..." +bootctl update +``` + +### 5. /etc Configuration Management + +#### Check /etc Configuration + +```bash +#!/bin/bash +# Check /etc configuration state + +echo "=== /etc Configuration Check ===" +echo "Date: $(date)" +echo + +# Check current /etc +echo "Current /etc contents:" +ls -la /etc/ + +# Check composefs state +echo "Composefs state:" +ls -la /sysroot/composefs/ + +# Check staged /etc +echo "Staged /etc contents:" +find /sysroot/composefs/ -name "etc" -type d -exec ls -la {} \; + +# Check for merge conflicts +echo "Checking for merge conflicts..." +find /etc/ -name "*.orig" -o -name "*.bak" -o -name "*.conflict" +``` + +#### Manual /etc Merge + +```bash +#!/bin/bash +# Manual /etc merge for testing + +echo "=== Manual /etc Merge ===" +echo "Date: $(date)" +echo + +# Create test directories +mkdir -p /tmp/pristine-etc +mkdir -p /tmp/current-etc +mkdir -p /tmp/new-etc + +# Create test files +echo "pristine config" > /tmp/pristine-etc/test.conf +echo "current config" > /tmp/current-etc/test.conf +echo "new config" > /tmp/new-etc/test.conf + +# Perform manual merge +echo "Performing manual merge..." +cp /tmp/pristine-etc/test.conf /tmp/merged-etc/test.conf + +# Apply current changes +echo "Applying current changes..." +# This would be done by the etc-merge library in practice + +# Apply new changes +echo "Applying new changes..." +# This would be done by the etc-merge library in practice + +# Clean up +rm -rf /tmp/pristine-etc /tmp/current-etc /tmp/new-etc /tmp/merged-etc +``` + +## Troubleshooting Guide + +### 1. Common Error Scenarios + +#### No Staged Deployment Error + +**Error**: `No staged deployment found` + +**Cause**: No staged deployment exists to finalize + +**Solution**: +```bash +# Check for staged deployment +ls -la /var/lib/composefs-transient-state/ + +# Create staged deployment if needed +echo "deployment-id" > /var/lib/composefs-transient-state/staged-deployment + +# Check composefs state +ls -la /sysroot/composefs/ +``` + +**Prevention**: +```bash +# Ensure staged deployment exists before finalization +if [ ! -f "/var/lib/composefs-transient-state/staged-deployment" ]; then + echo "Error: No staged deployment found" + exit 1 +fi +``` + +#### Non-Composefs Deployment Error + +**Error**: `Staged deployment is not a composefs deployment` + +**Cause**: Staged deployment is not a composefs deployment + +**Solution**: +```bash +# Check deployment type +cat /sysroot/composefs/*/deployment-id.origin + +# Verify composefs configuration +grep -i composefs /sysroot/composefs/*/deployment-id.origin +``` + +**Prevention**: +```bash +# Verify composefs deployment before staging +if ! grep -q "composefs" /path/to/deployment.origin; then + echo "Error: Not a composefs deployment" + exit 1 +fi +``` + +#### EROFS Mount Error + +**Error**: `Failed to mount EROFS image` + +**Cause**: EROFS image cannot be mounted + +**Solution**: +```bash +# Check EROFS image +file /path/to/image.erofs + +# Check mount point +ls -la /sysroot/ + +# Check permissions +ls -la /sysroot/composefs/ + +# Try manual mount +mount -t erofs /path/to/image.erofs /mnt/test +``` + +**Prevention**: +```bash +# Verify EROFS image before use +if ! file /path/to/image.erofs | grep -q "EROFS"; then + echo "Error: Invalid EROFS image" + exit 1 +fi +``` + +#### ESP Mount Error + +**Error**: `Failed to mount ESP partition` + +**Cause**: ESP partition cannot be mounted + +**Solution**: +```bash +# Check ESP partition +lsblk | grep -i efi + +# Check mount point +ls -la /boot/efi/ + +# Try manual mount +mount /dev/sda1 /mnt/esp +``` + +**Prevention**: +```bash +# Verify ESP partition before use +if ! lsblk | grep -q "EFI"; then + echo "Error: No ESP partition found" + exit 1 +fi +``` + +### 2. Debugging Techniques + +#### Enable Debug Logging + +```bash +# Set debug log level +export RUST_LOG=debug + +# Run command with debug output +bootc composefs-finalize-staged + +# Check debug logs +journalctl -u composefs-finalize-staged.service --since "1 hour ago" | grep DEBUG +``` + +#### Verbose Output + +```bash +# Enable verbose output +bootc composefs-finalize-staged -v + +# Check verbose logs +journalctl -u composefs-finalize-staged.service --since "1 hour ago" | grep -v INFO +``` + +#### System Information + +```bash +# Gather system information +uname -a +lsb_release -a +systemctl --version +bootc --version + +# Check system configuration +cat /etc/os-release +cat /proc/version +cat /proc/cpuinfo | head -20 +``` + +#### Composefs Diagnostics + +```bash +# Check composefs state +ls -la /sysroot/composefs/ +cat /var/lib/composefs-transient-state/staged-deployment + +# Check kernel cmdline +cat /proc/cmdline | grep -i composefs + +# Check mounted filesystems +mount | grep -i composefs +``` + +### 3. Recovery Procedures + +#### Service Recovery + +```bash +#!/bin/bash +# Service recovery script + +echo "=== Service Recovery ===" +echo "Date: $(date)" +echo + +# Stop service +echo "Stopping service..." +systemctl stop composefs-finalize-staged.service + +# Reset service state +echo "Resetting service state..." +systemctl reset-failed composefs-finalize-staged.service + +# Reload systemd +echo "Reloading systemd..." +systemctl daemon-reload + +# Start service +echo "Starting service..." +systemctl start composefs-finalize-staged.service + +# Check status +echo "Service status:" +systemctl status composefs-finalize-staged.service +``` + +#### Deployment Recovery + +```bash +#!/bin/bash +# Deployment recovery script + +echo "=== Deployment Recovery ===" +echo "Date: $(date)" +echo + +# Check staged deployment +echo "Checking staged deployment..." +if [ -f "/var/lib/composefs-transient-state/staged-deployment" ]; then + echo "Staged deployment found" + cat /var/lib/composefs-transient-state/staged-deployment +else + echo "No staged deployment found" +fi + +# Check composefs state +echo "Checking composefs state..." +ls -la /sysroot/composefs/ + +# Clean up if needed +echo "Cleaning up if needed..." +rm -f /var/lib/composefs-transient-state/staged-deployment + +echo "Deployment recovery complete" +``` + +### 4. Performance Analysis + +#### Execution Performance + +```bash +#!/bin/bash +# Execution performance analysis + +echo "=== Execution Performance Analysis ===" +echo "Date: $(date)" +echo + +# Time service execution +echo "Timing service execution..." +time systemctl start composefs-finalize-staged.service + +# Check resource usage +echo "Resource usage:" +ps aux | grep composefs-finalize-staged | awk '{sum+=$6} END {print sum/1024 " MB"}' + +# Check system load +echo "System load:" +uptime +``` + +#### Filesystem Performance + +```bash +#!/bin/bash +# Filesystem performance analysis + +echo "=== Filesystem Performance Analysis ===" +echo "Date: $(date)" +echo + +# Check disk usage +echo "Disk usage:" +df -h /sysroot + +# Check I/O usage +echo "I/O usage:" +iotop -bn1 | head -20 + +# Check mount performance +echo "Mount performance:" +time mount -t erofs /path/to/image.erofs /mnt/test +time umount /mnt/test +``` + +### 5. Monitoring and Alerting + +#### Health Check Script + +```bash +#!/bin/bash +# Health check script + +HEALTH_STATUS=0 + +echo "=== Composefs Finalize Staged Health Check ===" +echo "Date: $(date)" +echo + +# Check service status +echo "Checking service status..." +if ! systemctl is-active composefs-finalize-staged.service > /dev/null 2>&1; then + echo "ERROR: Service not active" + HEALTH_STATUS=1 +fi + +# Check staged deployment +echo "Checking staged deployment..." +if [ ! -f "/var/lib/composefs-transient-state/staged-deployment" ]; then + echo "WARNING: No staged deployment found" +fi + +# Check composefs state +echo "Checking composefs state..." +if [ ! -d "/sysroot/composefs" ]; then + echo "ERROR: Composefs state directory not found" + HEALTH_STATUS=1 +fi + +# Check EROFS support +echo "Checking EROFS support..." +if ! modprobe erofs > /dev/null 2>&1; then + echo "ERROR: EROFS module not available" + HEALTH_STATUS=1 +fi + +# Report health status +if [ $HEALTH_STATUS -eq 0 ]; then + echo "Health check passed" +else + echo "Health check failed" +fi + +exit $HEALTH_STATUS +``` + +#### Alerting Script + +```bash +#!/bin/bash +# Alerting script + +# Send alert to monitoring system +send_alert() { + local severity=$1 + local message=$2 + + curl -X POST "https://monitoring.example.com/alerts" \ + -H "Content-Type: application/json" \ + -d "{ + \"service\": \"composefs-finalize-staged\", + \"severity\": \"$severity\", + \"message\": \"$message\", + \"timestamp\": \"$(date -Iseconds)\" + }" +} + +# Check service health +if ! /usr/local/bin/composefs-finalize-staged-health-check.sh; then + send_alert "critical" "Composefs finalize staged service health check failed" +fi + +# Check service status +if ! systemctl is-active composefs-finalize-staged.service > /dev/null 2>&1; then + send_alert "critical" "Composefs finalize staged service not active" +fi + +# Check staged deployment +if [ ! -f "/var/lib/composefs-transient-state/staged-deployment" ]; then + send_alert "warning" "No staged deployment found" +fi +``` + +## Best Practices + +### 1. Usage Guidelines + +- **Systemd Integration**: Use systemd service for execution +- **Early Boot**: Execute early in boot process +- **Error Handling**: Implement proper error handling +- **Logging**: Use appropriate logging levels + +### 2. Security Considerations + +- **Privilege Requirements**: Ensure appropriate privileges +- **Sandboxing**: Use systemd sandboxing features +- **Access Control**: Limit filesystem access +- **Error Recovery**: Implement proper error recovery + +### 3. Performance Optimization + +- **Efficient Operations**: Use efficient filesystem operations +- **Resource Management**: Manage resources appropriately +- **Timeout Handling**: Handle timeouts gracefully +- **Error Recovery**: Implement proper error recovery + +This comprehensive examples and troubleshooting guide provides practical solutions for common issues and advanced debugging techniques for the bootc composefs-finalize-staged system. diff --git a/composefs-finalize-staged/bootc-composefs-finalize-staged-external-commands.md b/composefs-finalize-staged/bootc-composefs-finalize-staged-external-commands.md new file mode 100644 index 0000000..684fe78 --- /dev/null +++ b/composefs-finalize-staged/bootc-composefs-finalize-staged-external-commands.md @@ -0,0 +1,940 @@ +# bootc composefs-finalize-staged - External Commands Reference + +## Overview + +This document provides a comprehensive reference for all external commands used by `bootc composefs-finalize-staged` operations. These commands are essential for understanding the dependencies and integration points of the composefs-finalize-staged system. + +## Core Commands + +### bootc + +**Purpose**: Main bootc command for composefs-finalize-staged operations +**Usage**: `bootc composefs-finalize-staged` +**Dependencies**: None (core command) + +#### Examples +```bash +# Execute composefs-finalize-staged command +bootc composefs-finalize-staged + +# Check if command is available +bootc --help | grep composefs-finalize-staged +``` + +## Systemd Commands + +### systemctl + +**Purpose**: Systemd service management +**Usage**: `systemctl [options...]` +**Dependencies**: systemd + +#### Examples +```bash +# Start composefs-finalize-staged service +systemctl start composefs-finalize-staged.service + +# Enable service for automatic start +systemctl enable composefs-finalize-staged.service + +# Check service status +systemctl status composefs-finalize-staged.service + +# Stop service +systemctl stop composefs-finalize-staged.service + +# Restart service +systemctl restart composefs-finalize-staged.service + +# Reload systemd configuration +systemctl daemon-reload +``` + +### journalctl + +**Purpose**: Systemd journal viewing +**Usage**: `journalctl [options...]` +**Dependencies**: systemd + +#### Examples +```bash +# Show logs for composefs-finalize-staged service +journalctl -u composefs-finalize-staged.service + +# Show recent logs +journalctl -u composefs-finalize-staged.service -n 100 + +# Follow logs in real-time +journalctl -u composefs-finalize-staged.service -f + +# Show logs since specific time +journalctl -u composefs-finalize-staged.service --since "1 hour ago" + +# Show logs with priority +journalctl -u composefs-finalize-staged.service -p err + +# Show logs with timestamps +journalctl -u composefs-finalize-staged.service -o short-precise +``` + +## Filesystem Commands + +### mount + +**Purpose**: Mount filesystems +**Usage**: `mount [options...] ` +**Dependencies**: util-linux + +#### Examples +```bash +# Mount EROFS image +mount -t erofs /dev/loop0 /mnt/erofs + +# Mount ESP partition +mount /dev/sda1 /mnt/esp + +# Mount with specific options +mount -o ro,noexec /dev/loop0 /mnt/erofs + +# Mount bind +mount --bind /source /target + +# Show mounted filesystems +mount | grep composefs +``` + +### umount + +**Purpose**: Unmount filesystems +**Usage**: `umount [options...] ` +**Dependencies**: util-linux + +#### Examples +```bash +# Unmount filesystem +umount /mnt/erofs + +# Force unmount +umount -f /mnt/erofs + +# Lazy unmount +umount -l /mnt/erofs + +# Unmount all +umount -a +``` + +### losetup + +**Purpose**: Loop device management +**Usage**: `losetup [options...]` +**Dependencies**: util-linux + +#### Examples +```bash +# List loop devices +losetup -a + +# Create loop device +losetup /dev/loop0 /path/to/image.erofs + +# Delete loop device +losetup -d /dev/loop0 + +# Show loop device info +losetup -l /dev/loop0 +``` + +### fsync + +**Purpose**: Synchronize filesystem +**Usage**: `fsync [options...] ` +**Dependencies**: coreutils + +#### Examples +```bash +# Sync filesystem +fsync /path/to/file + +# Sync directory +fsync /path/to/directory + +# Force sync +fsync -f /path/to/file +``` + +## EROFS Commands + +### mkfs.erofs + +**Purpose**: Create EROFS filesystem +**Usage**: `mkfs.erofs [options...] ` +**Dependencies**: erofs-utils + +#### Examples +```bash +# Create EROFS image +mkfs.erofs -z lz4 /path/to/image.erofs /source/directory + +# Create with compression +mkfs.erofs -z lz4hc /path/to/image.erofs /source/directory + +# Create with specific block size +mkfs.erofs -b 4096 /path/to/image.erofs /source/directory + +# Create with file system label +mkfs.erofs -L "composefs-image" /path/to/image.erofs /source/directory +``` + +### erofs-fuse + +**Purpose**: Mount EROFS image using FUSE +**Usage**: `erofs-fuse [options...] ` +**Dependencies**: erofs-utils + +#### Examples +```bash +# Mount EROFS image with FUSE +erofs-fuse /path/to/image.erofs /mnt/erofs + +# Mount with specific options +erofs-fuse -o allow_other /path/to/image.erofs /mnt/erofs + +# Mount in background +erofs-fuse -f /path/to/image.erofs /mnt/erofs +``` + +## Bootloader Commands + +### grub-mkconfig + +**Purpose**: Generate GRUB configuration +**Usage**: `grub-mkconfig [options...]` +**Dependencies**: grub2 + +#### Examples +```bash +# Generate GRUB config +grub-mkconfig -o /boot/grub/grub.cfg + +# Generate with specific output +grub-mkconfig -o /boot/grub2/grub.cfg + +# Generate with verbose output +grub-mkconfig -v -o /boot/grub/grub.cfg + +# Generate for specific OS +grub-mkconfig -o /boot/grub/grub.cfg --os-prober +``` + +### grub-install + +**Purpose**: Install GRUB bootloader +**Usage**: `grub-install [options...] ` +**Dependencies**: grub2 + +#### Examples +```bash +# Install GRUB +grub-install /dev/sda + +# Install with specific directory +grub-install --boot-directory=/boot /dev/sda + +# Install with verbose output +grub-install -v /dev/sda + +# Install with UEFI support +grub-install --target=x86_64-efi --efi-directory=/boot/efi /dev/sda +``` + +### efibootmgr + +**Purpose**: EFI boot manager +**Usage**: `efibootmgr [options...]` +**Dependencies**: efibootmgr + +#### Examples +```bash +# List boot entries +efibootmgr + +# Create boot entry +efibootmgr -c -d /dev/sda -p 1 -L "Composefs" -l /EFI/composefs/grubx64.efi + +# Delete boot entry +efibootmgr -b 0000 -B + +# Set boot order +efibootmgr -o 0000,0001,0002 + +# Set next boot +efibootmgr -n 0000 +``` + +### bootctl + +**Purpose**: systemd-boot manager +**Usage**: `bootctl [options...]` +**Dependencies**: systemd-boot + +#### Examples +```bash +# List boot entries +bootctl list + +# Install systemd-boot +bootctl install + +# Update boot entries +bootctl update + +# Set default boot entry +bootctl set-default "composefs-1.0.0" + +# Show boot status +bootctl status +``` + +## File Operations Commands + +### cp + +**Purpose**: Copy files and directories +**Usage**: `cp [options...] ` +**Dependencies**: coreutils + +#### Examples +```bash +# Copy file +cp /source/file /destination/ + +# Copy directory recursively +cp -r /source/directory /destination/ + +# Copy with preserve attributes +cp -a /source/file /destination/ + +# Copy with verbose output +cp -v /source/file /destination/ +``` + +### mv + +**Purpose**: Move/rename files and directories +**Usage**: `mv [options...] ` +**Dependencies**: coreutils + +#### Examples +```bash +# Move file +mv /source/file /destination/ + +# Rename file +mv oldname newname + +# Move directory +mv /source/directory /destination/ + +# Move with verbose output +mv -v /source/file /destination/ +``` + +### rm + +**Purpose**: Remove files and directories +**Usage**: `rm [options...] ` +**Dependencies**: coreutils + +#### Examples +```bash +# Remove file +rm /path/to/file + +# Remove directory recursively +rm -r /path/to/directory + +# Force remove +rm -f /path/to/file + +# Remove with verbose output +rm -v /path/to/file +``` + +### ln + +**Purpose**: Create links +**Usage**: `ln [options...] ` +**Dependencies**: coreutils + +#### Examples +```bash +# Create symbolic link +ln -s /target/file /link/file + +# Create hard link +ln /target/file /link/file + +# Create link with verbose output +ln -v /target/file /link/file +``` + +## Directory Operations Commands + +### mkdir + +**Purpose**: Create directories +**Usage**: `mkdir [options...] ` +**Dependencies**: coreutils + +#### Examples +```bash +# Create directory +mkdir /path/to/directory + +# Create directory with parents +mkdir -p /path/to/directory + +# Create directory with permissions +mkdir -m 755 /path/to/directory + +# Create multiple directories +mkdir dir1 dir2 dir3 +``` + +### rmdir + +**Purpose**: Remove empty directories +**Usage**: `rmdir [options...] ` +**Dependencies**: coreutils + +#### Examples +```bash +# Remove empty directory +rmdir /path/to/directory + +# Remove directory with parents +rmdir -p /path/to/directory + +# Remove multiple directories +rmdir dir1 dir2 dir3 +``` + +### ls + +**Purpose**: List directory contents +**Usage**: `ls [options...] [file...]` +**Dependencies**: coreutils + +#### Examples +```bash +# List files +ls + +# List with details +ls -l + +# List all files +ls -a + +# List with human readable sizes +ls -lh + +# List with recursive +ls -R + +# List with sort by time +ls -lt +``` + +## Process Commands + +### ps + +**Purpose**: Process status +**Usage**: `ps [options...]` +**Dependencies**: procps + +#### Examples +```bash +# Show all processes +ps aux + +# Show process tree +ps -ef + +# Show specific process +ps -p 1234 + +# Show processes by user +ps -u username + +# Show processes by command +ps -C bootc +``` + +### kill + +**Purpose**: Send signals to processes +**Usage**: `kill [options...] ` +**Dependencies**: util-linux + +#### Examples +```bash +# Kill process +kill 1234 + +# Force kill process +kill -9 1234 + +# Send signal +kill -TERM 1234 + +# Kill by name +pkill bootc +``` + +## System Information Commands + +### uname + +**Purpose**: System information +**Usage**: `uname [options...]` +**Dependencies**: coreutils + +#### Examples +```bash +# Show system name +uname + +# Show all information +uname -a + +# Show kernel name +uname -s + +# Show kernel version +uname -r + +# Show machine type +uname -m +``` + +### hostname + +**Purpose**: Hostname operations +**Usage**: `hostname [options...]` +**Dependencies**: hostname + +#### Examples +```bash +# Show hostname +hostname + +# Show FQDN +hostname -f + +# Show short hostname +hostname -s + +# Show domain name +hostname -d +``` + +### lscpu + +**Purpose**: CPU information +**Usage**: `lscpu [options...]` +**Dependencies**: util-linux + +#### Examples +```bash +# Show CPU information +lscpu + +# Show in JSON format +lscpu -J + +# Show in extended format +lscpu -e + +# Show in parseable format +lscpu -p +``` + +### free + +**Purpose**: Memory information +**Usage**: `free [options...]` +**Dependencies**: procps + +#### Examples +```bash +# Show memory usage +free + +# Show in human readable format +free -h + +# Show in bytes +free -b + +# Show with total +free -t + +# Show with wide format +free -w +``` + +## Storage Commands + +### df + +**Purpose**: Disk space usage +**Usage**: `df [options...] [file...]` +**Dependencies**: coreutils + +#### Examples +```bash +# Show disk usage +df -h + +# Show specific filesystem +df -h /sysroot + +# Show inode usage +df -i + +# Show all filesystems +df -a +``` + +### du + +**Purpose**: Directory space usage +**Usage**: `du [options...] [file...]` +**Dependencies**: coreutils + +#### Examples +```bash +# Show directory usage +du -h /sysroot + +# Show total usage +du -sh /sysroot + +# Show usage by subdirectory +du -h --max-depth=1 /sysroot + +# Show usage of all files +du -ah /sysroot +``` + +### lsblk + +**Purpose**: List block devices +**Usage**: `lsblk [options...]` +**Dependencies**: util-linux + +#### Examples +```bash +# List block devices +lsblk + +# Show device tree +lsblk -f + +# Show device sizes +lsblk -b + +# Show device types +lsblk -d +``` + +## Network Commands + +### curl + +**Purpose**: HTTP client for registry operations +**Usage**: `curl [options...] ` +**Dependencies**: curl + +#### Examples +```bash +# Download file +curl -O https://example.com/file.tar + +# Get HTTP headers +curl -I https://example.com + +# POST data +curl -X POST -d "data" https://example.com + +# With authentication +curl -u username:password https://example.com + +# With custom headers +curl -H "Authorization: Bearer token" https://example.com +``` + +### wget + +**Purpose**: HTTP client for downloading files +**Usage**: `wget [options...] ` +**Dependencies**: wget + +#### Examples +```bash +# Download file +wget https://example.com/file.tar + +# Download with progress +wget --progress=bar https://example.com/file.tar + +# Download recursively +wget -r https://example.com/ + +# Download with authentication +wget --user=username --password=password https://example.com +``` + +## Archive Commands + +### tar + +**Purpose**: Archive operations +**Usage**: `tar [options...] [file...]` +**Dependencies**: tar + +#### Examples +```bash +# Create archive +tar -cf archive.tar file1 file2 + +# Extract archive +tar -xf archive.tar + +# List archive contents +tar -tf archive.tar + +# Create compressed archive +tar -czf archive.tar.gz file1 file2 + +# Extract compressed archive +tar -xzf archive.tar.gz +``` + +### gzip + +**Purpose**: Compression +**Usage**: `gzip [options...] [file...]` +**Dependencies**: gzip + +#### Examples +```bash +# Compress file +gzip file.txt + +# Decompress file +gzip -d file.txt.gz + +# Compress with custom level +gzip -9 file.txt + +# Keep original file +gzip -k file.txt +``` + +## Monitoring Commands + +### top + +**Purpose**: Process monitoring +**Usage**: `top [options...]` +**Dependencies**: procps + +#### Examples +```bash +# Show processes +top + +# Show specific user +top -u username + +# Show specific process +top -p 1234 + +# Show with custom delay +top -d 5 + +# Show with custom sort +top -o %CPU +``` + +### htop + +**Purpose**: Interactive process monitoring +**Usage**: `htop [options...]` +**Dependencies**: htop + +#### Examples +```bash +# Show processes +htop + +# Show specific user +htop -u username + +# Show specific process +htop -p 1234 + +# Show with custom delay +htop -d 5 +``` + +### iotop + +**Purpose**: I/O monitoring +**Usage**: `iotop [options...]` +**Dependencies**: iotop + +#### Examples +```bash +# Show I/O usage +iotop + +# Show only processes doing I/O +iotop -o + +# Show with custom delay +iotop -d 5 + +# Show with custom refresh +iotop -n 10 +``` + +## Security Commands + +### openssl + +**Purpose**: SSL/TLS operations +**Usage**: `openssl [options...]` +**Dependencies**: openssl + +#### Examples +```bash +# Generate private key +openssl genrsa -out key.pem 2048 + +# Generate certificate +openssl req -new -x509 -key key.pem -out cert.pem + +# Verify certificate +openssl verify cert.pem + +# Check certificate details +openssl x509 -in cert.pem -text -noout + +# Generate hash +openssl dgst -sha256 file.txt +``` + +### gpg + +**Purpose**: GPG operations +**Usage**: `gpg [options...]` +**Dependencies**: gnupg + +#### Examples +```bash +# Generate key pair +gpg --gen-key + +# List keys +gpg --list-keys + +# Sign file +gpg --sign file.txt + +# Verify signature +gpg --verify file.txt.asc + +# Encrypt file +gpg --encrypt file.txt +``` + +## Development Commands + +### make + +**Purpose**: Build automation +**Usage**: `make [target...]` +**Dependencies**: make + +#### Examples +```bash +# Build project +make + +# Clean build +make clean + +# Install +make install + +# Run tests +make test + +# Update generated files +make update-generated +``` + +### cargo + +**Purpose**: Rust package manager +**Usage**: `cargo [options...]` +**Dependencies**: rust + +#### Examples +```bash +# Build project +cargo build + +# Run project +cargo run + +# Run tests +cargo test + +# Check code +cargo check + +# Update dependencies +cargo update +``` + +### git + +**Purpose**: Version control +**Usage**: `git [options...]` +**Dependencies**: git + +#### Examples +```bash +# Clone repository +git clone https://github.com/containers/bootc.git + +# Check status +git status + +# Add files +git add . + +# Commit changes +git commit -m "message" + +# Push changes +git push +``` + +This comprehensive reference covers all external commands used by the bootc composefs-finalize-staged system, providing examples and usage patterns for each command. diff --git a/composefs-finalize-staged/bootc-composefs-finalize-staged-flowchart.md b/composefs-finalize-staged/bootc-composefs-finalize-staged-flowchart.md new file mode 100644 index 0000000..283e99a --- /dev/null +++ b/composefs-finalize-staged/bootc-composefs-finalize-staged-flowchart.md @@ -0,0 +1,417 @@ +# bootc composefs-finalize-staged - Process Flowchart + +## Overview + +This document provides a visual representation of the `bootc composefs-finalize-staged` process flow, showing the decision points, operations, and system state changes involved in finalizing staged composefs deployments. + +## Main Process Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ bootc composefs-finalize-staged โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Get Deployment Status โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Get composefs deployment status โ”‚ +โ”‚ โ€ข Validate booted composefs deployment โ”‚ +โ”‚ โ€ข Check for staged deployment โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Validate Staged Deployment โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Check if staged deployment exists โ”‚ +โ”‚ โ€ข Validate staged deployment is composefs โ”‚ +โ”‚ โ€ข Get staged composefs configuration โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Mount EROFS Image โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Open sysroot directory โ”‚ +โ”‚ โ€ข Mount booted EROFS image โ”‚ +โ”‚ โ€ข Create temporary mount point โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Perform /etc Merge โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Access pristine /etc from EROFS โ”‚ +โ”‚ โ€ข Access current /etc from system โ”‚ +โ”‚ โ€ข Access new /etc from staged deployment โ”‚ +โ”‚ โ€ข Perform 3-way merge โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Unmount EROFS Image โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Drop temporary mount โ”‚ +โ”‚ โ€ข Clean up EROFS mount โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Mount ESP Partition โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Get sysroot parent device โ”‚ +โ”‚ โ€ข Get ESP partition โ”‚ +โ”‚ โ€ข Mount ESP partition โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Update Bootloader Entries โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Determine bootloader type (GRUB vs systemd-boot) โ”‚ +โ”‚ โ€ข Determine boot type (BLS vs UKI) โ”‚ +โ”‚ โ€ข Update appropriate bootloader entries โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Complete Finalization โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Sync filesystem changes โ”‚ +โ”‚ โ€ข Update deployment state โ”‚ +โ”‚ โ€ข Complete finalization process โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Detailed Process Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Deployment Status Retrieval โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Get Composefs Status โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ composefs_deployment_status โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Check Kernel Cmdline โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Parse composefs parameter โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Extract composefs digest โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Validate composefs state โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Staged Deployment Validation โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Check Staged Deployment โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Staged Deployment Check โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ No Staged โ”‚ โ”‚ Staged Found โ”‚ โ”‚ +โ”‚ โ”‚ Deployment โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”‚ Check Composefs Type โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Return OK โ”‚โ”‚ โ”‚ โ”‚ โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ (No Action) โ”‚โ”‚ โ”‚ โ”‚ โ€ข Validate composefs deployment โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ”‚ โ€ข Get composefs configuration โ”‚โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ EROFS Image Operations โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Mount EROFS Image โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Open /sysroot directory โ”‚ +โ”‚ โ€ข Mount booted EROFS image using verity digest โ”‚ +โ”‚ โ€ข Create temporary mount point โ”‚ +โ”‚ โ€ข Access pristine /etc configuration โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ /etc Configuration Merge โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Three-Way Merge Process โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Pristine โ”‚ โ”‚ Current โ”‚ โ”‚ New โ”‚ โ”‚ +โ”‚ โ”‚ /etc โ”‚ โ”‚ /etc โ”‚ โ”‚ /etc โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ From EROFS โ”‚โ”‚ โ”‚ โ”‚ From System โ”‚โ”‚ โ”‚ โ”‚ From Staged โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Image โ”‚โ”‚ โ”‚ โ”‚ /etc โ”‚โ”‚ โ”‚ โ”‚ Deployment โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Compute Differences โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Compare pristine vs current โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Identify changes made by user โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Prepare for merge operation โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Perform Merge โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Apply pristine configuration as base โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Apply user changes from current โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Apply new changes from staged deployment โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Resolve conflicts if any โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ EROFS Cleanup โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Unmount EROFS Image โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Drop temporary mount โ”‚ +โ”‚ โ€ข Clean up EROFS mount โ”‚ +โ”‚ โ€ข Release file descriptors โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ ESP Partition Operations โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Mount ESP Partition โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Get sysroot parent device โ”‚ +โ”‚ โ€ข Get ESP partition information โ”‚ +โ”‚ โ€ข Mount ESP partition โ”‚ +โ”‚ โ€ข Access bootloader entries โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Bootloader Management โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Determine Bootloader Type โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Bootloader Type Check โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ GRUB โ”‚ โ”‚ systemd-boot โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ BLS Entries โ”‚โ”‚ โ”‚ โ”‚ BLS Entries โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ UKI Entries โ”‚โ”‚ โ”‚ โ”‚ UKI Entries โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Bootloader Operations Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Bootloader Operations โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ GRUB Bootloader โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Determine Boot Type โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ BLS Entries โ”‚ โ”‚ UKI Entries โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Update BLS โ”‚โ”‚ โ”‚ โ”‚ Update UKI Entries โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Entries โ”‚โ”‚ โ”‚ โ”‚ โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚โ”‚ โ”‚ โ”‚ โ€ข Rename staged UKI files โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ€ข Exchange โ”‚โ”‚ โ”‚ โ”‚ โ€ข Update GRUB configuration โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ entries โ”‚โ”‚ โ”‚ โ”‚ โ€ข Sync filesystem โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ€ข Update โ”‚โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ order โ”‚โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ systemd-boot Bootloader โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Determine Boot Type โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ BLS Entries โ”‚ โ”‚ UKI Entries โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Update BLS โ”‚โ”‚ โ”‚ โ”‚ Update UKI Entries โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Entries โ”‚โ”‚ โ”‚ โ”‚ โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚โ”‚ โ”‚ โ”‚ โ€ข Rename staged UKI files โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ€ข Exchange โ”‚โ”‚ โ”‚ โ”‚ โ€ข Sync filesystem โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ entries โ”‚โ”‚ โ”‚ โ”‚ โ€ข Update boot order โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ€ข Update โ”‚โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ order โ”‚โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Error Handling Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Error Detection โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Error Classification โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Deployment โ”‚ โ”‚ Filesystem โ”‚ โ”‚ Bootloader โ”‚ โ”‚ +โ”‚ โ”‚ Errors โ”‚ โ”‚ Errors โ”‚ โ”‚ Errors โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข No Staged โ”‚ โ”‚ โ€ข EROFS Mount โ”‚ โ”‚ โ€ข Entry Update โ”‚ โ”‚ +โ”‚ โ”‚ Deployment โ”‚ โ”‚ Failed โ”‚ โ”‚ Failed โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Non-Composefs โ”‚ โ”‚ โ€ข ESP Mount โ”‚ โ”‚ โ€ข Sync Failed โ”‚ โ”‚ +โ”‚ โ”‚ Deployment โ”‚ โ”‚ Failed โ”‚ โ”‚ โ€ข Permission โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Invalid State โ”‚ โ”‚ โ€ข Access Denied โ”‚ โ”‚ Denied โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Error Response โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Log error details โ”‚ +โ”‚ โ€ข Provide context information โ”‚ +โ”‚ โ€ข Return appropriate error code โ”‚ +โ”‚ โ€ข Clean up resources โ”‚ +โ”‚ โ€ข Notify systemd service โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Systemd Service Integration Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Systemd Service Lifecycle โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Service Start โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Service starts early in boot process โ”‚ +โ”‚ โ€ข After local-fs.target โ”‚ +โ”‚ โ€ข Before basic.target and final.target โ”‚ +โ”‚ โ€ข After systemd-journal-flush.service โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Command Execution โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Execute bootc composefs-finalize-staged โ”‚ +โ”‚ โ€ข With 5-minute timeout โ”‚ +โ”‚ โ€ข With sandboxing enabled โ”‚ +โ”‚ โ€ข With /etc read-only protection โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Service Completion โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Command completes successfully or fails โ”‚ +โ”‚ โ€ข Service remains active (RemainAfterExit=yes) โ”‚ +โ”‚ โ€ข System continues boot process โ”‚ +โ”‚ โ€ข Logs are written to journal โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## State Transitions Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ System States โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Initial State โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Staged Deployment Present โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Staged composefs deployment exists โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Booted composefs deployment active โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข System ready for finalization โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Finalization Process โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Mount EROFS image โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Perform /etc merge โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Update bootloader entries โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Sync filesystem changes โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Final State โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Staged deployment finalized โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Bootloader entries updated โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข System ready for next boot โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Staged deployment becomes active โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +This flowchart provides a comprehensive visual representation of the bootc composefs-finalize-staged process, showing all decision points, operations, and state transitions involved in finalizing staged composefs deployments. diff --git a/composefs-finalize-staged/bootc-composefs-finalize-staged-quick-reference.md b/composefs-finalize-staged/bootc-composefs-finalize-staged-quick-reference.md new file mode 100644 index 0000000..fcbbff1 --- /dev/null +++ b/composefs-finalize-staged/bootc-composefs-finalize-staged-quick-reference.md @@ -0,0 +1,336 @@ +# bootc composefs-finalize-staged - Quick Reference + +## Command Summary + +| Command | Purpose | Usage | +|---------|---------|-------| +| `composefs-finalize-staged` | Finalize staged composefs deployments | `bootc composefs-finalize-staged` | + +## Quick Commands + +### Basic Operations +```bash +# Execute composefs-finalize-staged command +bootc composefs-finalize-staged + +# Check if command is available +bootc --help | grep composefs-finalize-staged +``` + +### Systemd Service Operations +```bash +# Start service +systemctl start composefs-finalize-staged.service + +# Enable service +systemctl enable composefs-finalize-staged.service + +# Check service status +systemctl status composefs-finalize-staged.service + +# Stop service +systemctl stop composefs-finalize-staged.service + +# Restart service +systemctl restart composefs-finalize-staged.service +``` + +### Service Monitoring +```bash +# Check service logs +journalctl -u composefs-finalize-staged.service + +# Follow logs in real-time +journalctl -u composefs-finalize-staged.service -f + +# Show recent logs +journalctl -u composefs-finalize-staged.service -n 100 + +# Show logs since specific time +journalctl -u composefs-finalize-staged.service --since "1 hour ago" +``` + +## Common Options + +| Option | Purpose | Example | +|--------|---------|---------| +| `--help` | Show help | `bootc composefs-finalize-staged --help` | +| `--verbose` | Verbose output | `bootc composefs-finalize-staged -v` | +| `--quiet` | Quiet output | `bootc composefs-finalize-staged -q` | + +## Error Codes + +| Code | Meaning | Solution | +|------|---------|----------| +| 0 | Success | Command completed successfully | +| 1 | General error | Check logs for details | +| 2 | No staged deployment | Create staged deployment | +| 3 | Non-composefs deployment | Verify deployment type | +| 4 | EROFS mount error | Check EROFS image and mount point | +| 5 | ESP mount error | Check ESP partition and mount point | + +## Common Issues + +### No Staged Deployment +```bash +# Error: No staged deployment found +# Solution: Check for staged deployment +ls -la /var/lib/composefs-transient-state/ + +# Create staged deployment if needed +echo "deployment-id" > /var/lib/composefs-transient-state/staged-deployment +``` + +### Non-Composefs Deployment +```bash +# Error: Staged deployment is not a composefs deployment +# Solution: Check deployment type +cat /sysroot/composefs/*/deployment-id.origin + +# Verify composefs configuration +grep -i composefs /sysroot/composefs/*/deployment-id.origin +``` + +### EROFS Mount Error +```bash +# Error: Failed to mount EROFS image +# Solution: Check EROFS image +file /path/to/image.erofs + +# Check mount point +ls -la /sysroot/ + +# Try manual mount +mount -t erofs /path/to/image.erofs /mnt/test +``` + +### ESP Mount Error +```bash +# Error: Failed to mount ESP partition +# Solution: Check ESP partition +lsblk | grep -i efi + +# Check mount point +ls -la /boot/efi/ + +# Try manual mount +mount /dev/sda1 /mnt/esp +``` + +## Environment Variables + +| Variable | Purpose | Default | +|----------|---------|---------| +| `RUST_LOG` | Log level | `info` | +| `BOOTC_DEBUG` | Debug mode | `false` | +| `BOOTC_CONFIG` | Config file | `/etc/bootc/config.toml` | + +## Configuration Files + +| File | Purpose | Location | +|------|---------|----------| +| Main config | Bootc configuration | `/etc/bootc/config.toml` | +| Service file | Systemd service | `/usr/lib/systemd/system/composefs-finalize-staged.service` | +| Staged deployment | Staged deployment marker | `/var/lib/composefs-transient-state/staged-deployment` | +| Composefs state | Composefs state directory | `/sysroot/composefs/` | + +## Log Files + +| File | Purpose | Location | +|------|---------|----------| +| System logs | System messages | `/var/log/messages` | +| Journal logs | Systemd journal | `journalctl -u composefs-finalize-staged.service` | +| Bootc logs | Bootc specific | `/var/log/bootc/` | + +## Performance Tips + +### Optimize Operations +```bash +# Check system load +uptime + +# Check memory usage +free -h + +# Check disk usage +df -h /sysroot + +# Check I/O usage +iotop -bn1 | head -20 +``` + +### Monitor System +```bash +# Check service status +systemctl is-active composefs-finalize-staged.service + +# Check service logs +journalctl -u composefs-finalize-staged.service --since "1 hour ago" + +# Check system performance +top -bn1 | head -20 +``` + +## Security Considerations + +### Root Privileges +- All composefs-finalize-staged operations require root privileges +- Use `sudo` or switch to root user +- Check current user with `whoami` + +### Sandboxing +- Service runs with systemd sandboxing +- `ProtectHome=yes` - restricts home directory access +- `ReadOnlyPaths=/etc` - prevents /etc modification + +### Access Control +- Command accesses EROFS images for pristine configuration +- Command accesses ESP partition for bootloader operations +- Command manages system state for deployment management + +## Best Practices + +### Regular Operations +- Use systemd service for execution +- Execute early in boot process +- Monitor service status and logs +- Implement proper error handling + +### Development +- Use in composefs-backend branch +- Test with staged deployments +- Document procedures +- Monitor system health + +### Production +- Set up monitoring +- Configure alerts +- Regular testing +- Document procedures + +## Troubleshooting Steps + +1. **Check service status** + ```bash + systemctl status composefs-finalize-staged.service + ``` + +2. **Check service logs** + ```bash + journalctl -u composefs-finalize-staged.service --since "1 hour ago" + ``` + +3. **Check staged deployment** + ```bash + ls -la /var/lib/composefs-transient-state/ + cat /var/lib/composefs-transient-state/staged-deployment + ``` + +4. **Check composefs state** + ```bash + ls -la /sysroot/composefs/ + ``` + +5. **Check EROFS support** + ```bash + modprobe erofs + lsmod | grep erofs + ``` + +6. **Check ESP partition** + ```bash + lsblk | grep -i efi + ls -la /boot/efi/ + ``` + +## Quick Scripts + +### Health Check +```bash +#!/bin/bash +systemctl is-active composefs-finalize-staged.service && echo "Service healthy" +``` + +### Service Restart +```bash +#!/bin/bash +systemctl restart composefs-finalize-staged.service && echo "Service restarted" +``` + +### Log Check +```bash +#!/bin/bash +journalctl -u composefs-finalize-staged.service -n 50 +``` + +### Staged Deployment Check +```bash +#!/bin/bash +[ -f "/var/lib/composefs-transient-state/staged-deployment" ] && echo "Staged deployment found" || echo "No staged deployment" +``` + +## Integration Examples + +### Systemd Service +```bash +# Create service file +cat > /etc/systemd/system/composefs-finalize-staged.service << EOF +[Unit] +Description=Composefs Finalize Staged Deployment +Documentation=man:bootc(1) +DefaultDependencies=no + +RequiresMountsFor=/sysroot +After=local-fs.target +Before=basic.target final.target +After=systemd-journal-flush.service +Conflicts=final.target + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStop=/usr/bin/bootc composefs-finalize-staged +TimeoutStopSec=5m +ProtectHome=yes +ReadOnlyPaths=/etc +EOF + +# Enable service +systemctl daemon-reload +systemctl enable composefs-finalize-staged.service +``` + +### Cron Job +```bash +# Add to crontab +echo "0 2 * * * /usr/local/bin/composefs-finalize-staged-maintenance.sh" | crontab - +``` + +### Monitoring +```bash +# Check service health +if ! systemctl is-active composefs-finalize-staged.service > /dev/null 2>&1; then + echo "WARNING: Composefs finalize staged service not active" + # Send alert +fi +``` + +## Service Configuration + +### Service Dependencies +- `RequiresMountsFor=/sysroot` - Requires /sysroot to be mounted +- `After=local-fs.target` - Runs after local filesystems are mounted +- `Before=basic.target final.target` - Runs before basic and final targets +- `After=systemd-journal-flush.service` - Runs after journal is flushed + +### Service Security +- `ProtectHome=yes` - Protects home directory +- `ReadOnlyPaths=/etc` - Makes /etc read-only +- `TimeoutStopSec=5m` - 5-minute timeout for operations + +### Service Execution +- `Type=oneshot` - Runs once and exits +- `RemainAfterExit=yes` - Service remains active after completion +- `ExecStop=/usr/bin/bootc composefs-finalize-staged` - Command to execute + +This quick reference provides essential information for using the bootc composefs-finalize-staged system effectively. diff --git a/composefs-finalize-staged/bootc-composefs-finalize-staged-technical-guide.md b/composefs-finalize-staged/bootc-composefs-finalize-staged-technical-guide.md new file mode 100644 index 0000000..b4b30d3 --- /dev/null +++ b/composefs-finalize-staged/bootc-composefs-finalize-staged-technical-guide.md @@ -0,0 +1,559 @@ +# bootc composefs-finalize-staged - Technical Guide + +## Overview + +`bootc composefs-finalize-staged` is a hidden command specific to the `composefs-backend` branch that finalizes staged composefs deployments. This command is executed early in the boot process by a systemd service to complete the deployment of staged composefs images. + +## Purpose + +The composefs-finalize-staged command serves several critical functions: + +1. **Staged Deployment Finalization**: Completes the deployment of staged composefs images +2. **Boot Process Integration**: Executes early in the boot process via systemd service +3. **Filesystem Operations**: Performs EROFS mounting and /etc merging operations +4. **Bootloader Management**: Updates bootloader entries for staged deployments +5. **System State Management**: Manages composefs deployment state transitions + +## Command Structure + +```rust +#[cfg(feature = "composefs-backend")] +ComposefsFinalizeStaged, +``` + +The command is conditionally compiled only when the `composefs-backend` feature is enabled. + +## Core Functionality + +### Purpose + +The command finalizes staged composefs deployments by: +- Mounting the booted EROFS image to access pristine /etc configuration +- Performing 3-way merge of /etc configurations (pristine, current, new) +- Updating bootloader entries for staged deployments +- Managing bootloader-specific operations (GRUB vs systemd-boot) + +### Usage + +```bash +bootc composefs-finalize-staged +``` + +### Implementation + +```rust +pub(crate) async fn composefs_native_finalize() -> Result<()> { + let host = composefs_deployment_status().await?; + + let booted_composefs = host.require_composefs_booted()?; + + let Some(staged_depl) = host.status.staged.as_ref() else { + tracing::debug!("No staged deployment found"); + return Ok(()); + }; + + let staged_composefs = staged_depl.composefs.as_ref().ok_or(anyhow::anyhow!( + "Staged deployment is not a composefs deployment" + ))?; + + // Mount the booted EROFS image to get pristine etc + let sysroot = open_dir(CWD, "/sysroot")?; + let composefs_fd = mount_composefs_image(&sysroot, &booted_composefs.verity, false)?; + + let erofs_tmp_mnt = TempMount::mount_fd(&composefs_fd)?; + + // Perform the /etc merge + let pristine_etc = + Dir::open_ambient_dir(erofs_tmp_mnt.dir.path().join("etc"), ambient_authority())?; + let current_etc = Dir::open_ambient_dir("/etc", ambient_authority())?; + + let new_etc_path = Path::new(STATE_DIR_ABS) + .join(&staged_composefs.verity) + .join("etc"); + + let new_etc = Dir::open_ambient_dir(new_etc_path, ambient_authority())?; + + let (pristine_files, current_files, new_files) = + traverse_etc(&pristine_etc, ¤t_etc, &new_etc)?; + + let diff = compute_diff(&pristine_files, ¤t_files)?; + merge(¤t_etc, ¤t_files, &new_etc, &new_files, diff)?; + + // Unmount EROFS + drop(erofs_tmp_mnt); + + let sysroot_parent = get_sysroot_parent_dev()?; + // NOTE: Assumption here that ESP will always be present + let (esp_part, ..) = get_esp_partition(&sysroot_parent)?; + + let esp_mount = TempMount::mount_dev(&esp_part)?; + let boot_dir = Dir::open_ambient_dir("/sysroot/boot", ambient_authority()) + .context("Opening sysroot/boot")?; + + // NOTE: Assuming here we won't have two bootloaders at the same time + match booted_composefs.bootloader { + Bootloader::Grub => match staged_composefs.boot_type { + BootType::Bls => { + let entries_dir = boot_dir.open_dir("loader")?; + rename_exchange_bls_entries(&entries_dir)?; + } + BootType::Uki => finalize_staged_grub_uki(&esp_mount.fd, &boot_dir)?, + }, + + Bootloader::Systemd => match staged_composefs.boot_type { + BootType::Bls => { + let entries_dir = esp_mount.fd.open_dir("loader")?; + rename_exchange_bls_entries(&entries_dir)?; + } + BootType::Uki => rename_staged_uki_entries(&esp_mount.fd)?, + }, + }; + + Ok(()) +} +``` + +## Technical Details + +### 1. Deployment Status Retrieval + +The command first retrieves the current composefs deployment status: + +```rust +let host = composefs_deployment_status().await?; +let booted_composefs = host.require_composefs_booted()?; +``` + +### 2. Staged Deployment Validation + +The command validates that a staged deployment exists and is a composefs deployment: + +```rust +let Some(staged_depl) = host.status.staged.as_ref() else { + tracing::debug!("No staged deployment found"); + return Ok(()); +}; + +let staged_composefs = staged_depl.composefs.as_ref().ok_or(anyhow::anyhow!( + "Staged deployment is not a composefs deployment" +))?; +``` + +### 3. EROFS Image Mounting + +The command mounts the booted EROFS image to access pristine /etc configuration: + +```rust +let sysroot = open_dir(CWD, "/sysroot")?; +let composefs_fd = mount_composefs_image(&sysroot, &booted_composefs.verity, false)?; +let erofs_tmp_mnt = TempMount::mount_fd(&composefs_fd)?; +``` + +### 4. /etc Configuration Merging + +The command performs a 3-way merge of /etc configurations: + +```rust +let pristine_etc = + Dir::open_ambient_dir(erofs_tmp_mnt.dir.path().join("etc"), ambient_authority())?; +let current_etc = Dir::open_ambient_dir("/etc", ambient_authority())?; + +let new_etc_path = Path::new(STATE_DIR_ABS) + .join(&staged_composefs.verity) + .join("etc"); + +let new_etc = Dir::open_ambient_dir(new_etc_path, ambient_authority())?; + +let (pristine_files, current_files, new_files) = + traverse_etc(&pristine_etc, ¤t_etc, &new_etc)?; + +let diff = compute_diff(&pristine_files, ¤t_files)?; +merge(¤t_etc, ¤t_files, &new_etc, &new_files, diff)?; +``` + +### 5. Bootloader Management + +The command updates bootloader entries based on the bootloader type and boot type: + +```rust +match booted_composefs.bootloader { + Bootloader::Grub => match staged_composefs.boot_type { + BootType::Bls => { + let entries_dir = boot_dir.open_dir("loader")?; + rename_exchange_bls_entries(&entries_dir)?; + } + BootType::Uki => finalize_staged_grub_uki(&esp_mount.fd, &boot_dir)?, + }, + + Bootloader::Systemd => match staged_composefs.boot_type { + BootType::Bls => { + let entries_dir = esp_mount.fd.open_dir("loader")?; + rename_exchange_bls_entries(&entries_dir)?; + } + BootType::Uki => rename_staged_uki_entries(&esp_mount.fd)?, + }, +} +``` + +## Command Routing + +The command is routed through the main CLI dispatcher: + +```rust +#[cfg(feature = "composefs-backend")] +Opt::ComposefsFinalizeStaged => composefs_native_finalize().await, +``` + +## Systemd Integration + +### Service Definition + +The command is executed by a systemd service: + +```ini +[Unit] +Description=Composefs Finalize Staged Deployment +Documentation=man:bootc(1) +DefaultDependencies=no + +RequiresMountsFor=/sysroot +After=local-fs.target +Before=basic.target final.target +After=systemd-journal-flush.service +Conflicts=final.target + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStop=/usr/bin/bootc composefs-finalize-staged +TimeoutStopSec=5m +ProtectHome=yes +ReadOnlyPaths=/etc +``` + +### Service Characteristics + +- **Type**: oneshot - runs once and exits +- **RemainAfterExit**: yes - service remains active after completion +- **ExecStop**: executes the composefs-finalize-staged command +- **TimeoutStopSec**: 5 minutes - long timeout for slow media +- **ProtectHome**: yes - sandboxing for security +- **ReadOnlyPaths**: /etc - prevents modification of current /etc + +## Bootloader Operations + +### GRUB Bootloader + +#### BLS (Boot Loader Specification) Entries + +```rust +BootType::Bls => { + let entries_dir = boot_dir.open_dir("loader")?; + rename_exchange_bls_entries(&entries_dir)?; +} +``` + +#### UKI (Unified Kernel Image) Entries + +```rust +BootType::Uki => finalize_staged_grub_uki(&esp_mount.fd, &boot_dir)?, +``` + +### systemd-boot Bootloader + +#### BLS Entries + +```rust +BootType::Bls => { + let entries_dir = esp_mount.fd.open_dir("loader")?; + rename_exchange_bls_entries(&entries_dir)?; +} +``` + +#### UKI Entries + +```rust +BootType::Uki => rename_staged_uki_entries(&esp_mount.fd)?, +``` + +## Filesystem Operations + +### 1. EROFS Mounting + +The command mounts EROFS images for access to pristine configuration: + +```rust +let composefs_fd = mount_composefs_image(&sysroot, &booted_composefs.verity, false)?; +let erofs_tmp_mnt = TempMount::mount_fd(&composefs_fd)?; +``` + +### 2. ESP Partition Mounting + +The command mounts the ESP partition for bootloader operations: + +```rust +let sysroot_parent = get_sysroot_parent_dev()?; +let (esp_part, ..) = get_esp_partition(&sysroot_parent)?; +let esp_mount = TempMount::mount_dev(&esp_part)?; +``` + +### 3. /etc Configuration Merging + +The command performs 3-way merge of /etc configurations: + +- **Pristine**: Original configuration from EROFS image +- **Current**: Current system configuration +- **New**: New configuration from staged deployment + +## Error Handling + +### 1. Common Error Scenarios + +#### No Staged Deployment + +```rust +let Some(staged_depl) = host.status.staged.as_ref() else { + tracing::debug!("No staged deployment found"); + return Ok(()); +}; +``` + +#### Non-Composefs Deployment + +```rust +let staged_composefs = staged_depl.composefs.as_ref().ok_or(anyhow::anyhow!( + "Staged deployment is not a composefs deployment" +))?; +``` + +#### Filesystem Access Errors + +```rust +let sysroot = open_dir(CWD, "/sysroot")?; +let composefs_fd = mount_composefs_image(&sysroot, &booted_composefs.verity, false)?; +``` + +### 2. Error Recovery + +The command provides comprehensive error context: + +```rust +#[context("Getting composefs deployment status")] +pub(crate) async fn composefs_deployment_status() -> Result { + // Implementation with automatic error context +} +``` + +## Performance Characteristics + +### 1. Execution Time + +- **Fast**: Optimized for early boot execution +- **Efficient**: Minimal overhead for staging operations +- **Atomic**: Single atomic operation + +### 2. Resource Usage + +- **Low CPU**: Minimal CPU usage +- **Low Memory**: Minimal memory usage +- **Disk I/O**: Efficient filesystem operations + +### 3. System Impact + +- **Early Boot**: Executes early in boot process +- **Filesystem Access**: Accesses EROFS and ESP partitions +- **Bootloader Updates**: Updates bootloader entries + +## Security Considerations + +### 1. Privilege Requirements + +The command requires appropriate privileges for: +- Filesystem mounting operations +- Bootloader entry modifications +- System state management + +### 2. Sandboxing + +The systemd service provides sandboxing: +- **ProtectHome**: yes - restricts home directory access +- **ReadOnlyPaths**: /etc - prevents /etc modification + +### 3. Access Control + +The command accesses: +- **EROFS images**: For pristine configuration +- **ESP partition**: For bootloader operations +- **System state**: For deployment management + +## Integration Points + +### 1. Composefs Backend + +The command integrates with the composefs backend: + +```rust +#[cfg(feature = "composefs-backend")] +use crate::bootc_composefs::{ + finalize::composefs_native_finalize, rollback::composefs_rollback, status::composefs_booted, + switch::switch_composefs, update::upgrade_composefs, +}; +``` + +### 2. Systemd Service + +The command integrates with systemd for early boot execution: + +```ini +ExecStop=/usr/bin/bootc composefs-finalize-staged +``` + +### 3. Bootloader Management + +The command integrates with bootloader management: + +```rust +match booted_composefs.bootloader { + Bootloader::Grub => { /* GRUB operations */ } + Bootloader::Systemd => { /* systemd-boot operations */ } +} +``` + +## Use Cases + +### 1. Staged Deployment Finalization + +The primary use case is finalizing staged composefs deployments: + +```bash +# Executed by systemd service during boot +systemctl start composefs-finalize-staged.service +``` + +### 2. Boot Process Integration + +The command integrates with the boot process: + +```bash +# Service runs early in boot process +systemctl enable composefs-finalize-staged.service +``` + +### 3. Configuration Management + +The command manages /etc configuration merging: + +```bash +# Performs 3-way merge of /etc configurations +# - Pristine: Original from EROFS +# - Current: Current system +# - New: Staged deployment +``` + +### 4. Bootloader Updates + +The command updates bootloader entries: + +```bash +# Updates GRUB or systemd-boot entries +# - BLS entries for Boot Loader Specification +# - UKI entries for Unified Kernel Image +``` + +## Testing and Validation + +### 1. Unit Tests + +```rust +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test] + async fn test_composefs_native_finalize() { + // Test finalization process + let result = composefs_native_finalize().await; + assert!(result.is_ok()); + } +} +``` + +### 2. Integration Tests + +```rust +#[tokio::test] +async fn test_composefs_finalize_integration() { + // Test with staged deployment + let test_env = TestEnvironment::new().await.unwrap(); + + // Create staged deployment + test_env.create_staged_deployment().await.unwrap(); + + // Test finalization + let result = composefs_native_finalize().await; + assert!(result.is_ok()); +} +``` + +## Best Practices + +### 1. Usage Guidelines + +- **Systemd Integration**: Use systemd service for execution +- **Early Boot**: Execute early in boot process +- **Error Handling**: Implement proper error handling +- **Logging**: Use appropriate logging levels + +### 2. Security Considerations + +- **Privilege Requirements**: Ensure appropriate privileges +- **Sandboxing**: Use systemd sandboxing features +- **Access Control**: Limit filesystem access +- **Error Recovery**: Implement proper error recovery + +### 3. Performance Optimization + +- **Efficient Operations**: Use efficient filesystem operations +- **Resource Management**: Manage resources appropriately +- **Timeout Handling**: Handle timeouts gracefully +- **Error Recovery**: Implement proper error recovery + +## Future Enhancements + +### 1. Enhanced Error Handling + +Enhanced error handling and recovery: + +```rust +pub(crate) struct FinalizeOptions { + pub retry_attempts: u32, + pub timeout_seconds: u64, + pub rollback_on_failure: bool, +} +``` + +### 2. Performance Monitoring + +Performance monitoring and metrics: + +```rust +pub(crate) struct FinalizeMetrics { + pub execution_time: Duration, + pub files_processed: u64, + pub merge_operations: u64, +} +``` + +### 3. Configuration Options + +Configuration options for finalization: + +```rust +pub(crate) struct FinalizeConfig { + pub enable_etc_merge: bool, + pub enable_bootloader_update: bool, + pub backup_original: bool, +} +``` + +This technical guide provides comprehensive understanding of the bootc composefs-finalize-staged system's functionality, implementation, and usage patterns. diff --git a/composefs.md b/composefs.md new file mode 100644 index 0000000..3a28044 --- /dev/null +++ b/composefs.md @@ -0,0 +1,419 @@ +# bootc Composefs Integration - Technical Documentation + +## Overview + +This document explains how bootc utilizes Composefs as an alternative storage backend to OSTree. The composefs-backend branch introduces direct container image deployment without OSTree conversion. + +## What is Composefs? + +Composefs is a Linux kernel filesystem that mounts read-only EROFS images directly from userspace: + +- **Direct Container Support**: Mount OCI images without conversion +- **Kernel Performance**: No userspace daemon required +- **Built-in Security**: fsverity integration for integrity verification +- **Storage Efficiency**: EROFS compression and deduplication + +## Why Composefs is Needed + +### Main Branch (OSTree) Problems + +1. **Container Conversion**: OCI images must be converted to OSTree format +2. **Performance Overhead**: Userspace operations for file access +3. **Storage Inefficiency**: OSTree object model creates overhead +4. **Complex Deployment**: Multi-step conversion process + +### Composefs-Backend Solutions + +1. **Direct Container Support**: No conversion needed +2. **Kernel Performance**: Direct kernel mounting +3. **Storage Efficiency**: EROFS compression and layer deduplication +4. **Simplified Architecture**: Fewer moving parts + +## Architecture Comparison + +### Main Branch (OSTree Backend) +``` +Container Image โ†’ OSTree Conversion โ†’ OSTree Repository โ†’ Deployment +``` + +**Components:** +- OSTree repository with converted images +- Deployment objects for state management +- Userspace file access through OSTree library +- OCI to OSTree conversion layer + +### Composefs-Backend Branch +``` +Container Image โ†’ EROFS Image โ†’ Composefs Mount โ†’ Direct Access +``` + +**Components:** +- Composefs repository with EROFS images +- Direct kernel mounting via composefs +- Native container image support +- No conversion required + +## Technical Implementation + +### 1. Repository Structure + +**Main Branch:** +``` +/sysroot/ostree/ +โ”œโ”€โ”€ repo/objects/ # OSTree objects +โ”œโ”€โ”€ repo/refs/ # References +โ””โ”€โ”€ deploy/{id}/ # Deployment checkout + โ”œโ”€โ”€ usr/ # System files + โ”œโ”€โ”€ etc/ # Configuration + โ””โ”€โ”€ var/ # Variable data +``` + +**Composefs-Backend:** +``` +/sysroot/ +โ”œโ”€โ”€ composefs/ # EROFS images +โ”œโ”€โ”€ state/deploy/{id}/ # Deployment states +โ”‚ โ”œโ”€โ”€ etc/ # Merged /etc +โ”‚ โ”œโ”€โ”€ var -> # Symlink to shared /var +โ”‚ โ””โ”€โ”€ {id}.origin # Metadata +โ””โ”€โ”€ boot/ # Bootloader config + โ”œโ”€โ”€ loader/ # BLS entries + โ””โ”€โ”€ grub2/ # GRUB config +``` + +### 2. Image Storage + +**Main Branch (OSTree):** +```rust +// Must convert OCI to OSTree +let ostree_ref = ostree_container::OstreeImageReference { + sigverify: SignatureSource::ContainerPolicy, + imgref: ImageReference { + transport: Transport::Registry, + name: "quay.io/myorg/debian-bootc:v2.0".to_string(), + }, +}; + +let deployment = ostree_container::deploy::deploy(&sysroot, &ostree_ref, &deploy_opts)?; +``` + +**Composefs-Backend:** +```rust +// Direct OCI image pull +pub(crate) async fn pull_composefs_repo(transport: &String, image: &String) -> Result<(...)> { + let repo = open_composefs_repo(&rootfs_dir)?; + + // Pull directly from registry + let (id, verity) = composefs_oci_pull( + &Arc::new(repo), + &format!("{transport}:{image}"), + None, + None + ).await?; + + // Create EROFS filesystem + let mut fs = create_composefs_filesystem(&repo, &hex::encode(id), None)?; + let entries = fs.transform_for_boot(&repo)?; + let id = fs.commit_image(&repo, None)?; + + Ok((repo, entries, id, fs)) +} +``` + +### 3. Boot Configuration + +**Main Branch (BLS only):** +```rust +let bls_config = BLSConfig { + title: "bootc".to_string(), + options: Some("root=ostree:ostree=1:deploy-id={id}".to_string()), +}; +``` + +**Composefs-Backend (BLS + UKI):** +```rust +#[derive(ValueEnum, Debug, Copy, Clone)] +pub enum BootType { + Bls, // Boot Loader Specification + Uki, // Unified Kernel Image +} + +let bls_config = BLSConfig { + title: "bootc-composefs".to_string(), + options: Some("composefs=sha256:{digest}".to_string()), +}; +``` + +### 4. Kernel Integration + +**Main Branch:** +```rust +// Uses root= parameter +let root_param = format!("root=ostree:ostree=1:deploy-id={deployment_id}"); +``` + +**Composefs-Backend:** +```rust +// Uses composefs= parameter +pub const COMPOSEFS_CMDLINE: &str = "composefs"; + +pub(crate) struct ComposefsCmdline { + pub insecure: bool, + pub digest: Box, +} + +// Kernel parameter: composefs=sha256:abc123... or composefs=?sha256:abc123... (insecure) +``` + +## State Management + +### Main Branch (OSTree) +```rust +// OSTree deployment objects +let deployments = sysroot.deployments(); +let booted_deployment = sysroot.booted_deployment(); +``` + +### Composefs-Backend +```rust +// Custom state management +pub(crate) fn write_composefs_state( + root_path: &Utf8PathBuf, + deployment_id: Sha256HashValue, + imgref: &ImageReference, + staged: bool, + boot_type: BootType, + boot_digest: Option, +) -> Result<()> { + let state_path = root_path.join(format!("{STATE_DIR_RELATIVE}/{}", deployment_id.to_hex())); + + // Create deployment directory + create_dir_all(state_path.join("etc"))?; + + // Copy pristine /etc from EROFS image + copy_etc_to_state(&root_path, &deployment_id.to_hex(), &state_path)?; + + // Create symlink to shared /var + let actual_var_path = root_path.join(SHARED_VAR_PATH); + create_dir_all(&actual_var_path)?; + + symlink( + path_relative_to(state_path.as_std_path(), actual_var_path.as_std_path())?, + state_path.join("var"), + )?; + + // Write deployment metadata + let mut config = tini::Ini::new() + .section("origin") + .item(ORIGIN_CONTAINER, format!("ostree-unverified-image:{transport}{image_name}")); + + config = config + .section(ORIGIN_KEY_BOOT) + .item(ORIGIN_KEY_BOOT_TYPE, boot_type); + + if let Some(boot_digest) = boot_digest { + config = config + .section(ORIGIN_KEY_BOOT) + .item(ORIGIN_KEY_BOOT_DIGEST, boot_digest); + } + + // Write .origin file + state_dir.atomic_write( + format!("{}.origin", deployment_id.to_hex()), + config.to_string().as_bytes(), + )?; + + // Handle staged deployments + if staged { + std::fs::create_dir_all(COMPOSEFS_TRANSIENT_STATE_DIR)?; + let staged_depl_dir = cap_std::fs::Dir::open_ambient_dir( + COMPOSEFS_TRANSIENT_STATE_DIR, + cap_std::ambient_authority(), + )?; + + staged_depl_dir.atomic_write( + COMPOSEFS_STAGED_DEPLOYMENT_FNAME, + deployment_id.to_hex().as_bytes(), + )?; + } + + Ok(()) +} +``` + +## /etc Management + +### Main Branch (OSTree) +```rust +// OSTree 3-way merge +let pristine_etc = sysroot.deployment_get_origin_file(booted_deployment, "etc")?; +let current_etc = Dir::open_ambient_dir("/etc", ambient_authority())?; +let new_etc = sysroot.deployment_get_origin_file(staged_deployment, "etc")?; +let merged_etc = ostree_merge_etc(&pristine_etc, ¤t_etc, &new_etc)?; +``` + +### Composefs-Backend +```rust +// Composefs 3-way merge with EROFS +pub(crate) async fn composefs_native_finalize() -> Result<()> { + // Mount EROFS image for pristine /etc + let sysroot = open_dir(CWD, "/sysroot")?; + let composefs_fd = mount_composefs_image(&sysroot, &booted_composefs.verity, false)?; + let erofs_tmp_mnt = TempMount::mount_fd(&composefs_fd)?; + + // Perform 3-way merge + let pristine_etc = Dir::open_ambient_dir( + erofs_tmp_mnt.dir.path().join("etc"), + ambient_authority() + )?; + let current_etc = Dir::open_ambient_dir("/etc", ambient_authority())?; + + let new_etc_path = Path::new(STATE_DIR_ABS) + .join(&staged_composefs.verity) + .join("etc"); + let new_etc = Dir::open_ambient_dir(new_etc_path, ambient_authority())?; + + let (pristine_files, current_files, new_files) = + traverse_etc(&pristine_etc, ¤t_etc, &new_etc)?; + + let diff = compute_diff(&pristine_files, ¤t_files)?; + merge(¤t_etc, ¤t_files, &new_etc, &new_files, diff)?; + + Ok(()) +} +``` + +## Boot Process + +### Main Branch (OSTree) +1. **Kernel Boot**: `root=ostree:ostree=1:deploy-id={id}` +2. **OSTree Mount**: Mount OSTree repository +3. **Deployment Checkout**: Checkout deployment files +4. **Userspace Access**: Access files through OSTree library + +### Composefs-Backend +1. **Kernel Boot**: `composefs=sha256:{digest}` +2. **EROFS Mount**: Kernel directly mounts EROFS image +3. **Direct Access**: No userspace daemon required +4. **Verity Verification**: Built-in integrity checking + +## CLI Integration + +### Main Branch +```rust +// Direct OSTree operations +match opt { + Opt::Upgrade(opts) => upgrade(opts).await, + Opt::Switch(opts) => switch(opts).await, + Opt::Rollback(opts) => rollback(opts).await, +} +``` + +### Composefs-Backend +```rust +// Conditional backend selection +match opt { + Opt::Upgrade(opts) => { + #[cfg(feature = "composefs-backend")] + if composefs_booted()?.is_some() { + upgrade_composefs(opts).await + } else { + upgrade(opts).await + } + } + Opt::Switch(opts) => { + #[cfg(feature = "composefs-backend")] + if composefs_booted()?.is_some() { + switch_composefs(opts).await + } else { + switch(opts).await + } + } +} +``` + +## Systemd Integration + +### Main Branch +Uses standard OSTree systemd services. + +### Composefs-Backend +New systemd service for composefs finalization: + +```ini +[Unit] +Description=Composefs Finalize Staged Deployment +Documentation=man:bootc(1) +DefaultDependencies=no + +RequiresMountsFor=/sysroot +After=local-fs.target +Before=basic.target final.target + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStop=/usr/bin/bootc composefs-finalize-staged +TimeoutStopSec=5m +ProtectHome=yes +ReadOnlyPaths=/etc +``` + +## Key Differences + +| Aspect | Main Branch (OSTree) | Composefs-Backend | +|--------|---------------------|-------------------| +| **Storage** | OSTree repository | EROFS images | +| **Container Support** | Conversion required | Direct OCI support | +| **Boot Methods** | BLS only | BLS + UKI | +| **Kernel Integration** | Limited | Native composefs | +| **Performance** | Userspace overhead | Kernel-native | +| **Security** | External fsverity | Built-in fsverity | +| **Boot Process** | `root=ostree:...` | `composefs=sha256:...` | + +## External Commands + +### Composefs Operations +```bash +# Mount EROFS image +mount -t erofs /dev/loop0 /mnt + +# Create EROFS image +mkfs.erofs -o image.erofs /source/directory + +# Mount composefs +mount -t composefs /dev/loop0 /mnt + +# Create composefs image +composefs-util create /source /destination +``` + +### Container Registry +```bash +# Pull container image +podman pull quay.io/myorg/debian-bootc:v2.0 + +# Inspect image +podman inspect quay.io/myorg/debian-bootc:v2.0 +``` + +### Bootloader Configuration +```bash +# Update GRUB +grub2-mkconfig -o /boot/grub2/grub.cfg + +# Update systemd-boot +bootctl update +``` + +## Conclusion + +The composefs-backend branch provides significant improvements over the main branch: + +1. **Better Performance**: Kernel-native mounting eliminates userspace overhead +2. **Direct Container Support**: No conversion needed for OCI images +3. **Enhanced Security**: Built-in fsverity verification +4. **Storage Efficiency**: Better compression and deduplication +5. **Simplified Architecture**: Fewer moving parts, more reliable + +The conditional compilation approach allows gradual adoption while maintaining backward compatibility with the OSTree backend. diff --git a/edit/bootc-edit-external-commands.md b/edit/bootc-edit-external-commands.md new file mode 100644 index 0000000..7785fdc --- /dev/null +++ b/edit/bootc-edit-external-commands.md @@ -0,0 +1,883 @@ +# bootc edit - External Commands Reference + +## Overview + +This document provides a comprehensive reference for all external commands, system services, and tools that interact with or are used by the `bootc edit` system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc edit into larger systems. + +## Core System Commands + +### 1. bootc Commands + +#### bootc edit +**Purpose**: Edit host specification declaratively +**Usage**: `bootc edit [OPTIONS...]` +**External Dependencies**: +- `ostree` - For deployment management +- `podman` - For container registry access +- `systemd` - For service management +- `editor` - For interactive editing + +```bash +# Interactive editing +bootc edit + +# Edit from file +bootc edit --filename config.yaml + +# Quiet mode +bootc edit --quiet +``` + +#### bootc status +**Purpose**: Check system status and deployment state +**Usage**: `bootc status [OPTIONS...]` +**External Dependencies**: +- `ostree` - For deployment information +- `systemd` - For service status + +```bash +# Check current status +bootc status + +# Check status in JSON format +bootc status --json + +# Check specific deployment +bootc status --deployment=deployment-id +``` + +#### bootc switch +**Purpose**: Switch to different container image +**Usage**: `bootc switch [OPTIONS...]` +**External Dependencies**: +- `ostree` - For deployment management +- `podman` - For container registry access + +```bash +# Switch to different image +bootc switch quay.io/myorg/debian-bootc:v2.0 + +# Switch and apply immediately +bootc switch quay.io/myorg/debian-bootc:v2.0 --apply +``` + +#### bootc rollback +**Purpose**: Rollback to previous deployment +**Usage**: `bootc rollback [OPTIONS...]` +**External Dependencies**: +- `ostree` - For deployment switching +- `systemd` - For service management + +```bash +# Rollback to previous version +bootc rollback + +# Rollback to specific deployment +bootc rollback --deployment=deployment-id +``` + +### 2. OSTree Commands + +#### ostree admin status +**Purpose**: Check OSTree deployment status +**Usage**: `ostree admin status` +**Integration**: Used by `bootc status` for deployment information + +```bash +# Check deployment status +ostree admin status + +# Check specific deployment +ostree admin status --deployment=deployment-id +``` + +#### ostree admin deploy +**Purpose**: Deploy new OSTree deployment +**Usage**: `ostree admin deploy [OPTIONS...]` +**Integration**: Used internally by bootc for staging updates + +```bash +# Deploy new deployment +ostree admin deploy --os=debian-bootc deployment-id + +# Deploy with specific options +ostree admin deploy --os=debian-bootc --karg=console=ttyS0 deployment-id +``` + +#### ostree admin rollback +**Purpose**: Rollback to previous deployment +**Usage**: `ostree admin rollback [OPTIONS...]` +**Integration**: Used by `bootc rollback` for deployment switching + +```bash +# Rollback to previous deployment +ostree admin rollback + +# Rollback with specific options +ostree admin rollback --deployment=deployment-id +``` + +#### ostree admin cleanup +**Purpose**: Clean up old deployments and free space +**Usage**: `ostree admin cleanup [OPTIONS...]` +**Integration**: Used for disk space management + +```bash +# Clean up old deployments +ostree admin cleanup + +# Clean up with specific options +ostree admin cleanup --keep=2 +``` + +### 3. Container Registry Commands + +#### podman pull +**Purpose**: Pull container images from registry +**Usage**: `podman pull [OPTIONS...] IMAGE` +**Integration**: Used by bootc for downloading updates + +```bash +# Pull image from registry +podman pull quay.io/myorg/debian-bootc:latest + +# Pull with authentication +podman pull --creds=username:password quay.io/myorg/debian-bootc:latest + +# Pull specific tag +podman pull quay.io/myorg/debian-bootc:v1.2.3 +``` + +#### podman login +**Purpose**: Authenticate with container registry +**Usage**: `podman login [OPTIONS...] REGISTRY` +**Integration**: Required for private registry access + +```bash +# Login to registry +podman login quay.io + +# Login with specific credentials +podman login --username=myuser --password=mypass quay.io + +# Login with token +podman login --authfile=/path/to/auth.json quay.io +``` + +#### podman inspect +**Purpose**: Inspect container image metadata +**Usage**: `podman inspect [OPTIONS...] IMAGE` +**Integration**: Used for image validation and metadata extraction + +```bash +# Inspect image +podman inspect quay.io/myorg/debian-bootc:latest + +# Inspect specific configuration +podman inspect --format='{{.Config.Labels}}' quay.io/myorg/debian-bootc:latest + +# Inspect manifest +podman inspect --format='{{.Manifest}}' quay.io/myorg/debian-bootc:latest +``` + +## Editor Commands + +### 1. Text Editors + +#### vim +**Purpose**: Vi IMproved text editor +**Usage**: `vim [OPTIONS...] [FILE...]` +**Integration**: Primary editor for interactive editing + +```bash +# Edit file +vim config.yaml + +# Edit with specific options +vim -c "set syntax=yaml" config.yaml + +# Edit in read-only mode +vim -R config.yaml +``` + +#### nano +**Purpose**: Nano's ANOther editor +**Usage**: `nano [OPTIONS...] [FILE...]` +**Integration**: User-friendly editor for interactive editing + +```bash +# Edit file +nano config.yaml + +# Edit with specific options +nano -w config.yaml + +# Edit with line numbers +nano -l config.yaml +``` + +#### vi +**Purpose**: Visual editor +**Usage**: `vi [OPTIONS...] [FILE...]` +**Integration**: Fallback editor for interactive editing + +```bash +# Edit file +vi config.yaml + +# Edit with specific options +vi -c "set syntax=yaml" config.yaml +``` + +#### emacs +**Purpose**: GNU Emacs editor +**Usage**: `emacs [OPTIONS...] [FILE...]` +**Integration**: Alternative editor for interactive editing + +```bash +# Edit file +emacs config.yaml + +# Edit in terminal mode +emacs -nw config.yaml + +# Edit with specific options +emacs --eval "(yaml-mode)" config.yaml +``` + +### 2. Editor Configuration + +#### Environment Variables + +```bash +# Set default editor +export EDITOR=vim + +# Set editor with options +export EDITOR="vim -c 'set syntax=yaml'" + +# Set alternative editor +export EDITOR=nano +``` + +#### Editor Detection + +```bash +# Check available editors +which vim nano vi emacs + +# Check editor in PATH +command -v vim + +# Test editor availability +vim --version +``` + +## File System Commands + +### 1. File Operations + +#### cat +**Purpose**: Display file contents +**Usage**: `cat [OPTIONS...] [FILE...]` +**Integration**: Used for displaying configuration files + +```bash +# Display file contents +cat config.yaml + +# Display with line numbers +cat -n config.yaml + +# Display non-printing characters +cat -v config.yaml +``` + +#### cp +**Purpose**: Copy files +**Usage**: `cp [OPTIONS...] SOURCE DEST` +**Integration**: Used for backing up configuration files + +```bash +# Copy file +cp config.yaml config.yaml.backup + +# Copy with preserve attributes +cp -p config.yaml config.yaml.backup + +# Copy recursively +cp -r config/ config.backup/ +``` + +#### mv +**Purpose**: Move or rename files +**Usage**: `mv [OPTIONS...] SOURCE DEST` +**Integration**: Used for renaming configuration files + +```bash +# Rename file +mv config.yaml config.yaml.old + +# Move file +mv config.yaml /backup/config.yaml +``` + +#### rm +**Purpose**: Remove files +**Usage**: `rm [OPTIONS...] FILE...` +**Integration**: Used for cleaning up temporary files + +```bash +# Remove file +rm config.yaml + +# Remove with confirmation +rm -i config.yaml + +# Remove recursively +rm -r config/ +``` + +### 2. Directory Operations + +#### mkdir +**Purpose**: Create directories +**Usage**: `mkdir [OPTIONS...] DIRECTORY...` +**Integration**: Used for creating configuration directories + +```bash +# Create directory +mkdir -p /etc/bootc + +# Create with specific permissions +mkdir -m 755 /etc/bootc +``` + +#### ls +**Purpose**: List directory contents +**Usage**: `ls [OPTIONS...] [FILE...]` +**Integration**: Used for listing configuration files + +```bash +# List files +ls -la /etc/bootc/ + +# List with specific format +ls -l --time-style=full-iso /etc/bootc/ +``` + +#### find +**Purpose**: Search for files +**Usage**: `find [PATH...] [EXPRESSION...]` +**Integration**: Used for finding configuration files + +```bash +# Find configuration files +find /etc -name "*.yaml" -type f + +# Find files modified recently +find /etc/bootc -mtime -1 -type f +``` + +## YAML Processing Commands + +### 1. YAML Tools + +#### yq +**Purpose**: YAML processor +**Usage**: `yq [COMMAND] [OPTIONS...] [FILE...]` +**Integration**: Used for YAML manipulation and validation + +```bash +# Read YAML value +yq eval '.spec.image' config.yaml + +# Set YAML value +yq eval '.spec.image = "quay.io/myorg/debian-bootc:v2.0"' config.yaml + +# Validate YAML +yq eval '.' config.yaml +``` + +#### yaml-lint +**Purpose**: YAML syntax validator +**Usage**: `yaml-lint [OPTIONS...] [FILE...]` +**Integration**: Used for YAML validation + +```bash +# Validate YAML syntax +yaml-lint config.yaml + +# Validate with specific options +yaml-lint --config /etc/yaml-lint.conf config.yaml +``` + +#### python3 -m yaml +**Purpose**: Python YAML module +**Usage**: `python3 -m yaml [OPTIONS...] [FILE...]` +**Integration**: Used for YAML processing + +```bash +# Validate YAML +python3 -c "import yaml; yaml.safe_load(open('config.yaml'))" + +# Pretty print YAML +python3 -c "import yaml; print(yaml.dump(yaml.safe_load(open('config.yaml')), default_flow_style=False))" +``` + +### 2. JSON Tools + +#### jq +**Purpose**: JSON processor +**Usage**: `jq [OPTIONS...] [FILTER] [FILE...]` +**Integration**: Used for JSON processing and validation + +```bash +# Process JSON +jq '.spec.image' config.json + +# Validate JSON +jq '.' config.json + +# Convert YAML to JSON +yq eval -o=json config.yaml | jq '.' +``` + +## System Management Commands + +### 1. Process Management + +#### ps +**Purpose**: Display process information +**Usage**: `ps [OPTIONS...]` +**Integration**: Used for monitoring bootc processes + +```bash +# Display all processes +ps aux + +# Display specific process +ps aux | grep bootc + +# Display process tree +ps auxf +``` + +#### pgrep +**Purpose**: Find processes by name +**Usage**: `pgrep [OPTIONS...] PATTERN` +**Integration**: Used for finding bootc processes + +```bash +# Find bootc processes +pgrep bootc + +# Find with full command line +pgrep -f bootc +``` + +#### pkill +**Purpose**: Kill processes by name +**Usage**: `pkill [OPTIONS...] PATTERN` +**Integration**: Used for terminating bootc processes + +```bash +# Kill bootc processes +pkill bootc + +# Kill with signal +pkill -TERM bootc +``` + +### 2. System Information + +#### uname +**Purpose**: Display system information +**Usage**: `uname [OPTIONS...]` +**Integration**: Used for system identification + +```bash +# Display system information +uname -a + +# Display kernel version +uname -r + +# Display architecture +uname -m +``` + +#### hostname +**Purpose**: Display or set hostname +**Usage**: `hostname [OPTIONS...] [NAME]` +**Integration**: Used for system identification + +```bash +# Display hostname +hostname + +# Set hostname +hostname newhostname +``` + +#### whoami +**Purpose**: Display current user +**Usage**: `whoami [OPTIONS...]` +**Integration**: Used for user identification + +```bash +# Display current user +whoami + +# Display user ID +id +``` + +## Network Commands + +### 1. Connectivity Testing + +#### ping +**Purpose**: Test network connectivity +**Usage**: `ping [OPTIONS...] HOST` +**Integration**: Used for testing registry connectivity + +```bash +# Test connectivity +ping quay.io + +# Test with specific count +ping -c 4 quay.io + +# Test with specific interface +ping -I eth0 quay.io +``` + +#### curl +**Purpose**: HTTP client +**Usage**: `curl [OPTIONS...] URL` +**Integration**: Used for registry API calls + +```bash +# Test registry connectivity +curl -I https://quay.io/v2/ + +# Check registry API +curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \ + https://quay.io/v2/myorg/debian-bootc/manifests/latest +``` + +#### wget +**Purpose**: Download files from web servers +**Usage**: `wget [OPTIONS...] URL` +**Integration**: Alternative to curl for registry communication + +```bash +# Download registry manifest +wget -O manifest.json https://quay.io/v2/myorg/debian-bootc/manifests/latest + +# Download with authentication +wget --user=username --password=password https://quay.io/v2/token +``` + +### 2. DNS Resolution + +#### dig +**Purpose**: DNS lookup tool +**Usage**: `dig [OPTIONS...] DOMAIN` +**Integration**: Used for DNS resolution troubleshooting + +```bash +# Resolve registry domain +dig quay.io + +# Check specific DNS record +dig quay.io A + +# Check DNS server +dig @8.8.8.8 quay.io +``` + +#### nslookup +**Purpose**: DNS lookup tool +**Usage**: `nslookup [OPTIONS...] DOMAIN` +**Integration**: Alternative to dig for DNS troubleshooting + +```bash +# Resolve registry domain +nslookup quay.io + +# Check specific DNS record +nslookup -type=A quay.io +``` + +## Logging and Monitoring Commands + +### 1. System Logs + +#### journalctl +**Purpose**: Query systemd journal +**Usage**: `journalctl [OPTIONS...]` +**Integration**: Used for service and system log analysis + +```bash +# Check bootc service logs +journalctl -u bootc-fetch-apply-updates.service + +# Check recent logs +journalctl -n 100 + +# Check logs since boot +journalctl -b + +# Follow logs in real-time +journalctl -f +``` + +#### dmesg +**Purpose**: Display kernel ring buffer +**Usage**: `dmesg [OPTIONS...]` +**Integration**: Used for kernel-level troubleshooting + +```bash +# Display kernel messages +dmesg + +# Display recent messages +dmesg -T + +# Display with timestamps +dmesg -T | tail -50 +``` + +### 2. File Monitoring + +#### tail +**Purpose**: Display last lines of files +**Usage**: `tail [OPTIONS...] [FILE...]` +**Integration**: Used for monitoring log files + +```bash +# Follow log file +tail -f /var/log/bootc.log + +# Display last lines +tail -n 100 /var/log/bootc.log +``` + +#### head +**Purpose**: Display first lines of files +**Usage**: `head [OPTIONS...] [FILE...]` +**Integration**: Used for viewing file headers + +```bash +# Display first lines +head -n 20 config.yaml + +# Display first bytes +head -c 100 config.yaml +``` + +## Backup and Recovery Commands + +### 1. Archive Commands + +#### tar +**Purpose**: Archive files +**Usage**: `tar [OPTIONS...] [FILE...]` +**Integration**: Used for backup creation + +```bash +# Create backup +tar -czf backup.tar.gz /etc/bootc + +# Extract backup +tar -xzf backup.tar.gz + +# List archive contents +tar -tzf backup.tar.gz +``` + +#### rsync +**Purpose**: Synchronize files +**Usage**: `rsync [OPTIONS...] SRC DEST` +**Integration**: Used for backup synchronization + +```bash +# Synchronize files +rsync -av /etc/bootc/ /backup/bootc/ + +# Synchronize with remote +rsync -av /etc/bootc/ user@host:/backup/bootc/ +``` + +### 2. Version Control + +#### git +**Purpose**: Version control system +**Usage**: `git [COMMAND] [OPTIONS...]` +**Integration**: Used for configuration version control + +```bash +# Initialize repository +git init + +# Add files +git add config.yaml + +# Commit changes +git commit -m "Update configuration" + +# Check status +git status +``` + +## Security Commands + +### 1. File Permissions + +#### chmod +**Purpose**: Change file permissions +**Usage**: `chmod [OPTIONS...] MODE FILE...` +**Integration**: Used for setting file permissions + +```bash +# Set permissions +chmod 644 config.yaml + +# Set permissions recursively +chmod -R 755 /etc/bootc +``` + +#### chown +**Purpose**: Change file ownership +**Usage**: `chown [OPTIONS...] OWNER[:GROUP] FILE...` +**Integration**: Used for setting file ownership + +```bash +# Change ownership +chown root:root config.yaml + +# Change ownership recursively +chown -R root:root /etc/bootc +``` + +#### umask +**Purpose**: Set file creation mask +**Usage**: `umask [OPTIONS...] [MASK]` +**Integration**: Used for setting default permissions + +```bash +# Set umask +umask 022 + +# Display current umask +umask +``` + +### 2. Encryption + +#### gpg +**Purpose**: GNU Privacy Guard +**Usage**: `gpg [COMMAND] [OPTIONS...]` +**Integration**: Used for signature verification + +```bash +# Verify signature +gpg --verify signature.asc config.yaml + +# Import public key +gpg --import public.key + +# List keys +gpg --list-keys +``` + +#### openssl +**Purpose**: OpenSSL command line tool +**Usage**: `openssl [COMMAND] [OPTIONS...]` +**Integration**: Used for certificate and key management + +```bash +# Check certificate +openssl x509 -in certificate.crt -text -noout + +# Verify certificate chain +openssl verify -CAfile ca.crt certificate.crt +``` + +## Performance Monitoring Commands + +### 1. System Resources + +#### top +**Purpose**: Display running processes +**Usage**: `top [OPTIONS...]` +**Integration**: Used for process monitoring + +```bash +# Display processes +top + +# Display specific process +top -p $(pgrep bootc) +``` + +#### htop +**Purpose**: Interactive process viewer +**Usage**: `htop [OPTIONS...]` +**Integration**: Used for system resource monitoring + +```bash +# Start htop +htop + +# Monitor specific process +htop -p $(pgrep bootc) +``` + +#### free +**Purpose**: Display memory usage +**Usage**: `free [OPTIONS...]` +**Integration**: Used for memory monitoring + +```bash +# Display memory usage +free -h + +# Display in specific format +free -m +``` + +### 2. Disk Usage + +#### df +**Purpose**: Display filesystem disk space usage +**Usage**: `df [OPTIONS...] [FILE...]` +**Integration**: Used for disk space monitoring + +```bash +# Check disk usage +df -h + +# Check specific filesystem +df -h /sysroot + +# Check inode usage +df -i +``` + +#### du +**Purpose**: Display directory space usage +**Usage**: `du [OPTIONS...] [FILE...]` +**Integration**: Used for directory space analysis + +```bash +# Check directory usage +du -sh /etc/bootc + +# Check OSTree usage +du -sh /sysroot/ostree +``` + +This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc edit system. diff --git a/edit/bootc-edit-flowchart.md b/edit/bootc-edit-flowchart.md new file mode 100644 index 0000000..0a8cbec --- /dev/null +++ b/edit/bootc-edit-flowchart.md @@ -0,0 +1,321 @@ +# bootc edit - Process Flowchart + +## Overview + +This document provides a visual representation of the `bootc edit` process flow, showing the decision points, operations, and state transitions involved in editing bootc host specifications. + +## Main Process Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ bootc edit โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Initialize System โ”‚ +โ”‚ โ€ข Get storage interface โ”‚ +โ”‚ โ€ข Get OSTree repository โ”‚ +โ”‚ โ€ข Get current system status โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Load Configuration โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Filename โ”‚ โ”‚ Interactive Mode โ”‚ โ”‚ +โ”‚ โ”‚ Provided? โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Load from File โ”‚ โ”‚ โ€ข Create temporary file โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Open file โ”‚ โ”‚ โ€ข Write current config to temp โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Parse YAML โ”‚ โ”‚ โ€ข Spawn editor with temp file โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Validate โ”‚ โ”‚ โ€ข Wait for editor completion โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ€ข Read modified config โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Parse and Validate YAML โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Deserialize to Host structure โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Validate schema โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Check required fields โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Compare Configurations โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ new_host.spec == host.spec? โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Yes โ”‚ โ”‚ No โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Print: โ”‚โ”‚ โ”‚ โ”‚ Validate Transition โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ "Edit โ”‚โ”‚ โ”‚ โ”‚ โ€ข Check image changes โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ cancelled, โ”‚โ”‚ โ”‚ โ”‚ โ€ข Validate boot order โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ no changes โ”‚โ”‚ โ”‚ โ”‚ โ€ข Verify system state โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ made" โ”‚โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ–ผ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Return โ”‚โ”‚ โ”‚ โ”‚ Create RequiredHostSpec โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Success โ”‚โ”‚ โ”‚ โ”‚ โ€ข Extract image reference โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ”‚ โ€ข Validate required fields โ”‚โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Determine Change Type โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ boot_order changed? โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Yes โ”‚ โ”‚ No โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Execute โ”‚โ”‚ โ”‚ โ”‚ Image Change Process โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Rollback โ”‚โ”‚ โ”‚ โ”‚ โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ€ข Call โ”‚โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ rollback โ”‚โ”‚ โ”‚ โ”‚ โ”‚ Pull New Image โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ€ข Update โ”‚โ”‚ โ”‚ โ”‚ โ”‚ โ€ข Authenticate with โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ boot โ”‚โ”‚ โ”‚ โ”‚ โ”‚ registry โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ order โ”‚โ”‚ โ”‚ โ”‚ โ”‚ โ€ข Download image layers โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ”‚ โ”‚ โ€ข Convert to OSTree โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ€ข Validate image โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Return โ”‚โ”‚ โ”‚ โ”‚ โ”‚ โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Success โ”‚โ”‚ โ”‚ โ”‚ โ–ผ โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ”‚ Stage New Deployment โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ€ข Create new deployment โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ€ข Configure bootloader โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ€ข Update system status โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ€ข Preserve /etc and /var โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Update System Status โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Update system modification time โ”‚ +โ”‚ โ€ข Refresh system status โ”‚ +โ”‚ โ€ข Update deployment information โ”‚ +โ”‚ โ€ข Log configuration changes โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Success โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Configuration applied successfully โ”‚ +โ”‚ โ€ข System ready for next boot โ”‚ +โ”‚ โ€ข Changes staged for application โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Editor Integration Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Editor Selection โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Check Environment โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ $EDITOR set? โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Yes โ”‚ โ”‚ No โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Use $EDITOR โ”‚โ”‚ โ”‚ โ”‚ Check Backup Editors โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ€ข Split โ”‚โ”‚ โ”‚ โ”‚ โ€ข nano โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ command โ”‚โ”‚ โ”‚ โ”‚ โ€ข vim โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ€ข Extract โ”‚โ”‚ โ”‚ โ”‚ โ€ข vi โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ program โ”‚โ”‚ โ”‚ โ”‚ โ€ข Check /usr/bin/ โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ–ผ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ Editor Found? โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ–ผ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ Yes โ”‚ โ”‚ No โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ Use Backup โ”‚โ”‚ โ”‚ โ”‚Errorโ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ Editor โ”‚โ”‚ โ”‚ โ”‚ โ”‚โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Launch Editor โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Create command with editor program โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Add editor arguments โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Add temporary file path โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Execute with lifecycle binding โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Wait for completion โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Error Handling Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Error Detection โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Error Classification โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Editor โ”‚ โ”‚ Configuration โ”‚ โ”‚ System โ”‚ โ”‚ +โ”‚ โ”‚ Errors โ”‚ โ”‚ Errors โ”‚ โ”‚ Errors โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข $EDITOR โ”‚ โ”‚ โ€ข Invalid YAML โ”‚ โ”‚ โ€ข Not bootc โ”‚ โ”‚ +โ”‚ โ”‚ unset โ”‚ โ”‚ โ€ข Schema โ”‚ โ”‚ compatible โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Editor not โ”‚ โ”‚ validation โ”‚ โ”‚ โ€ข Image not โ”‚ โ”‚ +โ”‚ โ”‚ found โ”‚ โ”‚ โ€ข Missing โ”‚ โ”‚ found โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Editor โ”‚ โ”‚ fields โ”‚ โ”‚ โ€ข Registry โ”‚ โ”‚ +โ”‚ โ”‚ execution โ”‚ โ”‚ โ€ข Invalid โ”‚ โ”‚ error โ”‚ โ”‚ +โ”‚ โ”‚ failed โ”‚ โ”‚ values โ”‚ โ”‚ โ€ข OSTree error โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Error Response โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Display error message โ”‚ +โ”‚ โ€ข Provide context information โ”‚ +โ”‚ โ€ข Suggest remediation steps โ”‚ +โ”‚ โ€ข Return appropriate exit code โ”‚ +โ”‚ โ€ข Clean up temporary files โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## State Transitions + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ System States โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Current State โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Normal โ”‚ โ”‚ Rollback โ”‚ โ”‚ +โ”‚ โ”‚ Boot โ”‚ โ”‚ Queued โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Image: v1.0 โ”‚ โ”‚ โ€ข Image: v1.0 โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Boot: normal โ”‚ โ”‚ โ€ข Boot: rollback โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Edit Operation โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Image โ”‚ โ”‚ Boot Order โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Change โ”‚ โ”‚ Change โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ€ข Pull new โ”‚ โ”‚ โ€ข Execute rollback โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ image โ”‚ โ”‚ โ€ข Update boot order โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ€ข Stage โ”‚ โ”‚ โ€ข Preserve state โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ deployment โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ New State โ”‚ โ”‚ New State โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Image: v2.0 โ”‚ โ”‚ โ€ข Image: v1.0 โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Boot: normal โ”‚ โ”‚ โ€ข Boot: normal โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Staged: v2.0 โ”‚ โ”‚ โ€ข Rollback: queued โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Configuration Validation Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Configuration Input โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ YAML Parsing โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Parse YAML syntax โ”‚ +โ”‚ โ€ข Deserialize to Host structure โ”‚ +โ”‚ โ€ข Validate required fields โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Schema Validation โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Validate Host structure โ”‚ +โ”‚ โ€ข Check HostSpec fields โ”‚ +โ”‚ โ€ข Verify ImageReference format โ”‚ +โ”‚ โ€ข Validate BootOrder values โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Transition Validation โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Compare with current configuration โ”‚ +โ”‚ โ€ข Check for valid state transitions โ”‚ +โ”‚ โ€ข Verify image accessibility โ”‚ +โ”‚ โ€ข Validate boot order changes โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Validation Result โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Valid โ”‚ โ”‚ Invalid โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Proceed with โ”‚ โ”‚ โ€ข Display error message โ”‚ โ”‚ +โ”‚ โ”‚ changes โ”‚ โ”‚ โ€ข Provide context โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Apply โ”‚ โ”‚ โ€ข Suggest fixes โ”‚ โ”‚ +โ”‚ โ”‚ configuration โ”‚ โ”‚ โ€ข Return error โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +This flowchart provides a comprehensive visual representation of the bootc edit process, showing all decision points, operations, and state transitions involved in editing bootc host specifications. diff --git a/edit/bootc-edit-technical-guide.md b/edit/bootc-edit-technical-guide.md new file mode 100644 index 0000000..1cae281 --- /dev/null +++ b/edit/bootc-edit-technical-guide.md @@ -0,0 +1,476 @@ +# bootc edit - Technical Guide + +## Overview + +`bootc edit` is a declarative configuration management command that allows users to modify the host specification of a bootc-managed system. It operates similarly to `kubectl apply`, providing both interactive and programmatic interfaces for system configuration changes. + +## Purpose + +The edit command serves several critical functions: + +1. **Declarative Configuration**: Apply changes to system configuration declaratively +2. **Interactive Editing**: Use system editor for interactive configuration changes +3. **Programmatic Interface**: Apply configuration from files for automation +4. **State Management**: Maintain system state consistency across changes +5. **Validation**: Ensure configuration changes are valid and safe + +## Command Syntax + +```bash +bootc edit [OPTIONS...] +``` + +### Basic Usage + +```bash +# Interactive editing (opens in $EDITOR) +bootc edit + +# Edit from file +bootc edit --filename /path/to/config.yaml + +# Quiet mode (no progress output) +bootc edit --quiet +``` + +## Command Options + +| Option | Description | Default | Required | +|--------|-------------|---------|----------| +| `-f`, `--filename` | Use filename to edit system specification | `None` | No | +| `--quiet` | Don't display progress | `false` | No | + +## Architecture Overview + +### 1. Configuration Structure + +The bootc edit system operates on a `Host` structure that contains: + +```rust +pub struct Host { + pub resource: k8sapitypes::Resource, // Kubernetes-style metadata + pub spec: HostSpec, // Host specification + pub status: HostStatus, // Current system status +} +``` + +### 2. Host Specification + +The `HostSpec` contains the editable configuration: + +```rust +pub struct HostSpec { + pub image: Option, // Container image reference + pub boot_order: BootOrder, // Boot ordering configuration +} +``` + +### 3. Supported Changes + +Only changes to the `spec` section are honored: +- **Image Reference**: Change the container image source +- **Boot Order**: Modify boot ordering (rollback configuration) + +## Technical Implementation + +### 1. Edit Command Structure + +```rust +pub(crate) struct EditOpts { + pub(crate) filename: Option, // Optional file input + pub(crate) quiet: bool, // Progress suppression +} +``` + +### 2. Edit Process Flow + +```rust +async fn edit(opts: EditOpts) -> Result<()> { + // 1. Get system storage and OSTree + let sysroot = &get_storage().await?; + let ostree = sysroot.get_ostree()?; + let repo = &ostree.repo(); + + // 2. Get current system status + let (booted_deployment, _deployments, host) = + crate::status::get_status_require_booted(ostree)?; + + // 3. Load new configuration + let new_host: Host = if let Some(filename) = opts.filename { + // Load from file + let mut r = std::io::BufReader::new(std::fs::File::open(filename)?); + serde_yaml::from_reader(&mut r)? + } else { + // Interactive editing + let tmpf = tempfile::NamedTempFile::new()?; + serde_yaml::to_writer(std::io::BufWriter::new(tmpf.as_file()), &host)?; + crate::utils::spawn_editor(&tmpf)?; + tmpf.as_file().seek(std::io::SeekFrom::Start(0))?; + serde_yaml::from_reader(&mut tmpf.as_file())? + }; + + // 4. Validate changes + if new_host.spec == host.spec { + println!("Edit cancelled, no changes made."); + return Ok(()); + } + + // 5. Verify transition + host.spec.verify_transition(&new_host.spec)?; + let new_spec = RequiredHostSpec::from_spec(&new_host.spec)?; + + // 6. Apply changes + if host.spec.boot_order != new_host.spec.boot_order { + return crate::deploy::rollback(sysroot).await; + } + + // 7. Pull and stage new image + let fetched = crate::deploy::pull(repo, new_spec.image, None, opts.quiet, prog.clone()).await?; + let stateroot = booted_deployment.osname(); + crate::deploy::stage(sysroot, &stateroot, &fetched, &new_spec, prog.clone()).await?; + + // 8. Update system + sysroot.update_mtime()?; + + Ok(()) +} +``` + +### 3. Editor Integration + +The system supports multiple editors through the `spawn_editor` function: + +```rust +pub(crate) fn spawn_editor(tmpf: &tempfile::NamedTempFile) -> Result<()> { + let editor_variables = ["EDITOR"]; + let backup_editors = ["nano", "vim", "vi"]; + + let editor = editor_variables.into_iter().find_map(std::env::var_os); + let editor = if let Some(e) = editor.as_ref() { + e.to_str() + } else { + backup_editors + .into_iter() + .find(|v| std::path::Path::new("/usr/bin").join(v).exists()) + }; + + let editor = editor.ok_or_else(|| anyhow::anyhow!("$EDITOR is unset, and no backup editor found"))?; + let mut editor_args = editor.split_ascii_whitespace(); + let argv0 = editor_args.next().ok_or_else(|| anyhow::anyhow!("Invalid editor: {editor}"))?; + + Command::new(argv0) + .args(editor_args) + .arg(tmpf.path()) + .lifecycle_bind() + .run_inherited() + .with_context(|| format!("Invoking editor {editor} failed")) +} +``` + +## Configuration Format + +### 1. YAML Structure + +The configuration is stored in YAML format with the following structure: + +```yaml +apiVersion: v1 +kind: Host +metadata: + name: localhost + namespace: default +spec: + image: quay.io/myorg/debian-bootc:latest + bootOrder: "normal" # or "rollback" +status: + staged: null + booted: + image: quay.io/myorg/debian-bootc:v1.0.0 + digest: sha256:abc123... + version: "1.0.0" + rollback: + image: quay.io/myorg/debian-bootc:v0.9.0 + digest: sha256:def456... + version: "0.9.0" + rollbackQueued: false + otherDeployments: [] +``` + +### 2. Image Reference Format + +```yaml +spec: + image: + transport: "registry" + name: "quay.io/myorg/debian-bootc" + tag: "latest" + # or + digest: "sha256:abc123..." +``` + +### 3. Boot Order Options + +```yaml +spec: + bootOrder: "normal" # Normal boot order + # or + bootOrder: "rollback" # Rollback to previous deployment +``` + +## Usage Patterns + +### 1. Interactive Editing + +```bash +# Set editor environment variable +export EDITOR=vim + +# Edit configuration interactively +bootc edit +``` + +**Process**: +1. Current configuration is written to temporary file +2. System editor is launched with temporary file +3. User makes changes and saves +4. Changes are validated and applied + +### 2. File-Based Editing + +```bash +# Create configuration file +cat > config.yaml << EOF +apiVersion: v1 +kind: Host +metadata: + name: localhost +spec: + image: quay.io/myorg/debian-bootc:v2.0.0 + bootOrder: "normal" +EOF + +# Apply configuration +bootc edit --filename config.yaml +``` + +**Process**: +1. Configuration is loaded from file +2. Changes are validated +3. Configuration is applied to system + +### 3. Image Switching + +```bash +# Switch to different image +bootc edit --filename - << EOF +apiVersion: v1 +kind: Host +metadata: + name: localhost +spec: + image: quay.io/myorg/debian-bootc:v2.0.0 +EOF +``` + +### 4. Rollback Configuration + +```bash +# Configure rollback +bootc edit --filename - << EOF +apiVersion: v1 +kind: Host +metadata: + name: localhost +spec: + image: quay.io/myorg/debian-bootc:latest + bootOrder: "rollback" +EOF +``` + +## State Transitions + +### 1. Image Changes + +When the image reference changes: +1. **Validation**: Verify new image exists and is accessible +2. **Download**: Pull new container image from registry +3. **Staging**: Stage new image for next boot +4. **Status Update**: Update system status + +### 2. Boot Order Changes + +When boot order changes: +1. **Validation**: Verify rollback deployment exists +2. **Rollback**: Execute rollback operation +3. **Status Update**: Update boot order configuration + +### 3. No Changes + +When no changes are detected: +1. **Message**: Display "Edit cancelled, no changes made" +2. **Exit**: Return without making changes + +## Error Handling + +### 1. Editor Errors + +```rust +// Editor not found +$EDITOR is unset, and no backup editor found + +// Editor execution failed +Invoking editor vim failed +``` + +### 2. Configuration Errors + +```rust +// Invalid YAML +Error parsing YAML: invalid syntax + +// Invalid configuration +Error: invalid host specification +``` + +### 3. System Errors + +```rust +// System not bootc compatible +Error: system is not bootc compatible + +// Image not found +Error: image not found in registry +``` + +## Integration Points + +### 1. OSTree Integration + +- **Deployment Management**: Uses OSTree for deployment operations +- **Status Queries**: Queries OSTree for current system state +- **Staging**: Uses OSTree staging for new deployments + +### 2. Container Registry Integration + +- **Image Pulling**: Uses container registry for image downloads +- **Authentication**: Supports registry authentication +- **Signature Verification**: Validates image signatures + +### 3. Systemd Integration + +- **Service Management**: Coordinates with systemd services +- **Status Updates**: Updates system status through systemd + +## Security Considerations + +### 1. Configuration Validation + +- **Schema Validation**: Validates configuration against schema +- **Transition Validation**: Ensures safe state transitions +- **Image Verification**: Verifies image signatures and authenticity + +### 2. Editor Security + +- **Editor Selection**: Uses secure editor selection process +- **Temporary Files**: Uses secure temporary file handling +- **Process Isolation**: Isolates editor process execution + +### 3. System Security + +- **Privilege Escalation**: Requires appropriate privileges +- **State Consistency**: Maintains system state consistency +- **Rollback Safety**: Ensures safe rollback operations + +## Performance Considerations + +### 1. Configuration Loading + +- **File I/O**: Efficient file reading and writing +- **Memory Usage**: Minimal memory footprint for configuration +- **Parsing**: Fast YAML parsing and validation + +### 2. Editor Launch + +- **Process Spawning**: Efficient editor process creation +- **Temporary Files**: Fast temporary file operations +- **Editor Detection**: Quick editor availability checking + +### 3. System Updates + +- **Incremental Updates**: Only updates changed components +- **Status Caching**: Caches system status for performance +- **Validation Caching**: Caches validation results + +## Troubleshooting + +### 1. Editor Issues + +```bash +# Check editor availability +which vim nano vi + +# Set editor explicitly +export EDITOR=/usr/bin/vim +bootc edit +``` + +### 2. Configuration Issues + +```bash +# Validate YAML syntax +yaml-lint config.yaml + +# Check configuration schema +bootc edit --filename config.yaml --dry-run +``` + +### 3. System Issues + +```bash +# Check system status +bootc status + +# Check system compatibility +bootc status --json | jq '.status.booted' +``` + +## Best Practices + +### 1. Configuration Management + +- **Version Control**: Store configurations in version control +- **Validation**: Validate configurations before applying +- **Backup**: Backup current configuration before changes +- **Testing**: Test configurations in staging environment + +### 2. Editor Usage + +- **Editor Selection**: Use reliable editors (vim, nano) +- **Environment Variables**: Set EDITOR environment variable +- **Backup Editors**: Ensure backup editors are available +- **Editor Configuration**: Configure editor for YAML editing + +### 3. System Integration + +- **Automation**: Use file-based editing for automation +- **Monitoring**: Monitor system status after changes +- **Rollback**: Test rollback procedures regularly +- **Documentation**: Document configuration changes + +## Future Enhancements + +### 1. Planned Features + +- **Dry Run Mode**: Preview changes without applying +- **Configuration Templates**: Predefined configuration templates +- **Validation Rules**: Custom validation rules +- **Change Tracking**: Track configuration changes over time + +### 2. Integration Improvements + +- **API Support**: REST API for configuration management +- **Web Interface**: Web-based configuration editor +- **Configuration Sync**: Synchronize configurations across systems +- **Audit Logging**: Comprehensive audit logging + +This technical guide provides comprehensive understanding of the bootc edit system's architecture, implementation, and usage patterns. diff --git a/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-examples-troubleshooting.md b/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-examples-troubleshooting.md new file mode 100644 index 0000000..491548f --- /dev/null +++ b/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-examples-troubleshooting.md @@ -0,0 +1,614 @@ +# bootc exec-in-host-mount-namespace - Examples and Troubleshooting + +## Overview + +This document provides practical examples and troubleshooting guidance for the `bootc exec-in-host-mount-namespace` system, covering common use cases, error scenarios, and debugging techniques. + +## Common Use Cases + +### 1. Container Operations + +#### Execute Commands in Host Namespace + +```bash +#!/bin/bash +# Execute commands in host mount namespace + +echo "=== Host Namespace Operations ===" +echo "Date: $(date)" +echo + +# List host filesystem +echo "Listing host filesystem:" +bootc exec-in-host-mount-namespace ls / + +# Check host system status +echo "Checking host system status:" +bootc exec-in-host-mount-namespace systemctl status + +# View host processes +echo "Viewing host processes:" +bootc exec-in-host-mount-namespace ps aux + +# Check host storage +echo "Checking host storage:" +bootc exec-in-host-mount-namespace df -h +``` + +#### Mount Operations in Host Namespace + +```bash +#!/bin/bash +# Mount operations in host namespace + +echo "=== Host Mount Operations ===" +echo "Date: $(date)" +echo + +# Mount filesystem in host namespace +echo "Mounting filesystem in host namespace:" +bootc exec-in-host-mount-namespace mount /dev/sda1 /mnt + +# Check mount points +echo "Checking mount points:" +bootc exec-in-host-mount-namespace mount | grep /mnt + +# Unmount filesystem +echo "Unmounting filesystem:" +bootc exec-in-host-mount-namespace umount /mnt +``` + +### 2. Installation Support + +#### Installation Operations + +```bash +#!/bin/bash +# Installation operations using host namespace + +echo "=== Installation Operations ===" +echo "Date: $(date)" +echo + +# Create directories in host filesystem +echo "Creating directories in host filesystem:" +bootc exec-in-host-mount-namespace mkdir -p /var/lib/bootc +bootc exec-in-host-mount-namespace mkdir -p /etc/bootc + +# Copy files to host filesystem +echo "Copying files to host filesystem:" +bootc exec-in-host-mount-namespace cp /source/config.toml /etc/bootc/ + +# Set permissions +echo "Setting permissions:" +bootc exec-in-host-mount-namespace chmod 644 /etc/bootc/config.toml +bootc exec-in-host-mount-namespace chown root:root /etc/bootc/config.toml +``` + +#### Bootloader Operations + +```bash +#!/bin/bash +# Bootloader operations in host namespace + +echo "=== Bootloader Operations ===" +echo "Date: $(date)" +echo + +# Update GRUB configuration +echo "Updating GRUB configuration:" +bootc exec-in-host-mount-namespace grub-mkconfig -o /boot/grub/grub.cfg + +# Install GRUB +echo "Installing GRUB:" +bootc exec-in-host-mount-namespace grub-install /dev/sda + +# Update initramfs +echo "Updating initramfs:" +bootc exec-in-host-mount-namespace update-initramfs -u +``` + +### 3. Debugging and Maintenance + +#### System Diagnostics + +```bash +#!/bin/bash +# System diagnostics using host namespace + +echo "=== System Diagnostics ===" +echo "Date: $(date)" +echo + +# Check system information +echo "System information:" +bootc exec-in-host-mount-namespace uname -a +bootc exec-in-host-mount-namespace hostname +bootc exec-in-host-mount-namespace lscpu + +# Check memory usage +echo "Memory usage:" +bootc exec-in-host-mount-namespace free -h + +# Check disk usage +echo "Disk usage:" +bootc exec-in-host-mount-namespace df -h + +# Check process information +echo "Process information:" +bootc exec-in-host-mount-namespace ps aux | head -20 +``` + +#### Log Analysis + +```bash +#!/bin/bash +# Log analysis using host namespace + +echo "=== Log Analysis ===" +echo "Date: $(date)" +echo + +# Check system logs +echo "System logs:" +bootc exec-in-host-mount-namespace journalctl --since "1 hour ago" | head -50 + +# Check specific service logs +echo "Service logs:" +bootc exec-in-host-mount-namespace journalctl -u bootc-* --since "1 hour ago" + +# Check kernel logs +echo "Kernel logs:" +bootc exec-in-host-mount-namespace dmesg | tail -20 +``` + +### 4. System Integration + +#### Service Management + +```bash +#!/bin/bash +# Service management using host namespace + +echo "=== Service Management ===" +echo "Date: $(date)" +echo + +# Check service status +echo "Service status:" +bootc exec-in-host-mount-namespace systemctl status bootc-* + +# Start services +echo "Starting services:" +bootc exec-in-host-mount-namespace systemctl start bootc-* + +# Enable services +echo "Enabling services:" +bootc exec-in-host-mount-namespace systemctl enable bootc-* + +# Reload systemd +echo "Reloading systemd:" +bootc exec-in-host-mount-namespace systemctl daemon-reload +``` + +#### Network Operations + +```bash +#!/bin/bash +# Network operations using host namespace + +echo "=== Network Operations ===" +echo "Date: $(date)" +echo + +# Check network interfaces +echo "Network interfaces:" +bootc exec-in-host-mount-namespace ip addr show + +# Check network connections +echo "Network connections:" +bootc exec-in-host-mount-namespace netstat -tuln + +# Test network connectivity +echo "Network connectivity:" +bootc exec-in-host-mount-namespace ping -c 3 8.8.8.8 +``` + +## Troubleshooting Guide + +### 1. Common Error Scenarios + +#### Missing Command Error + +**Error**: `Missing command` + +**Cause**: No command provided to execute + +**Solution**: +```bash +# Provide a command +bootc exec-in-host-mount-namespace ls / + +# Or use a shell +bootc exec-in-host-mount-namespace /bin/bash +``` + +**Prevention**: +```bash +# Check if command is provided +if [ $# -eq 0 ]; then + echo "Error: No command provided" + exit 1 +fi + +# Execute command +bootc exec-in-host-mount-namespace "$@" +``` + +#### Namespace Access Error + +**Error**: `open pid1 mountns: No such file or directory` + +**Cause**: Cannot access host mount namespace + +**Solution**: +```bash +# Check if /proc/1/ns/mnt exists +ls -la /proc/1/ns/mnt + +# Check if running as root +whoami + +# Run as root +sudo bootc exec-in-host-mount-namespace ls / +``` + +**Prevention**: +```bash +# Check namespace availability +if [ ! -e /proc/1/ns/mnt ]; then + echo "Error: Host mount namespace not available" + exit 1 +fi + +# Check privileges +if [ "$EUID" -ne 0 ]; then + echo "Error: Must run as root" + exit 1 +fi +``` + +#### setns Error + +**Error**: `setns: Operation not permitted` + +**Cause**: Insufficient privileges for namespace switching + +**Solution**: +```bash +# Run as root +sudo bootc exec-in-host-mount-namespace ls / + +# Check capabilities +getcap /usr/bin/bootc + +# Add capabilities if needed +setcap cap_sys_admin+ep /usr/bin/bootc +``` + +**Prevention**: +```bash +# Check privileges +if [ "$EUID" -ne 0 ]; then + echo "Error: Must run as root for namespace operations" + exit 1 +fi +``` + +#### Command Not Found Error + +**Error**: `exec: command not found` + +**Cause**: Command not found in host namespace + +**Solution**: +```bash +# Use full path +bootc exec-in-host-mount-namespace /bin/ls / + +# Check command availability +bootc exec-in-host-mount-namespace which ls + +# Use absolute path +bootc exec-in-host-mount-namespace /usr/bin/ls / +``` + +**Prevention**: +```bash +# Check command availability first +if ! bootc exec-in-host-mount-namespace which "$1" > /dev/null 2>&1; then + echo "Error: Command not found: $1" + exit 1 +fi +``` + +### 2. Debugging Techniques + +#### Enable Debug Logging + +```bash +# Set debug log level +export RUST_LOG=debug + +# Run command with debug output +bootc exec-in-host-mount-namespace ls / + +# Check debug logs +journalctl -u bootc-* --since "1 hour ago" | grep DEBUG +``` + +#### Verbose Output + +```bash +# Enable verbose output +bootc exec-in-host-mount-namespace -v ls / + +# Check verbose logs +journalctl -u bootc-* --since "1 hour ago" | grep -v INFO +``` + +#### System Information + +```bash +# Gather system information +uname -a +lsb_release -a +systemctl --version +bootc --version + +# Check system configuration +cat /etc/os-release +cat /proc/version +cat /proc/cpuinfo | head -20 +``` + +#### Namespace Diagnostics + +```bash +# Check namespace information +ls -la /proc/1/ns/ +ls -la /proc/self/ns/ + +# Check namespace differences +diff /proc/1/ns/mnt /proc/self/ns/mnt + +# Check namespace capabilities +cat /proc/self/status | grep Ns +``` + +### 3. Recovery Procedures + +#### Namespace Recovery + +```bash +#!/bin/bash +# Namespace recovery script + +echo "=== Namespace Recovery ===" +echo "Date: $(date)" +echo + +# Check namespace availability +echo "Checking namespace availability..." +if [ ! -e /proc/1/ns/mnt ]; then + echo "ERROR: Host mount namespace not available" + exit 1 +fi + +# Check privileges +echo "Checking privileges..." +if [ "$EUID" -ne 0 ]; then + echo "ERROR: Must run as root" + exit 1 +fi + +# Test namespace access +echo "Testing namespace access..." +if ! bootc exec-in-host-mount-namespace ls / > /dev/null 2>&1; then + echo "ERROR: Cannot access host namespace" + exit 1 +fi + +echo "Namespace recovery successful" +``` + +#### Command Recovery + +```bash +#!/bin/bash +# Command recovery script + +echo "=== Command Recovery ===" +echo "Date: $(date)" +echo + +# Check command availability +echo "Checking command availability..." +if ! bootc exec-in-host-mount-namespace which "$1" > /dev/null 2>&1; then + echo "ERROR: Command not found: $1" + echo "Available commands:" + bootc exec-in-host-mount-namespace ls /bin + exit 1 +fi + +# Test command execution +echo "Testing command execution..." +if ! bootc exec-in-host-mount-namespace "$1" --help > /dev/null 2>&1; then + echo "WARNING: Command may not work as expected" +fi + +echo "Command recovery successful" +``` + +### 4. Performance Analysis + +#### Execution Performance + +```bash +#!/bin/bash +# Execution performance analysis + +echo "=== Execution Performance Analysis ===" +echo "Date: $(date)" +echo + +# Time command execution +echo "Timing command execution..." +time bootc exec-in-host-mount-namespace ls / + +# Check resource usage +echo "Resource usage:" +ps aux | grep bootc | awk '{sum+=$6} END {print sum/1024 " MB"}' + +# Check system load +echo "System load:" +uptime +``` + +#### Namespace Performance + +```bash +#!/bin/bash +# Namespace performance analysis + +echo "=== Namespace Performance Analysis ===" +echo "Date: $(date)" +echo + +# Time namespace operations +echo "Timing namespace operations..." +time bootc exec-in-host-mount-namespace uname -a + +# Check namespace overhead +echo "Namespace overhead:" +time bootc exec-in-host-mount-namespace /bin/true +time /bin/true + +# Check system performance +echo "System performance:" +bootc exec-in-host-mount-namespace top -bn1 | head -20 +``` + +### 5. Monitoring and Alerting + +#### Health Check Script + +```bash +#!/bin/bash +# Health check script + +HEALTH_STATUS=0 + +echo "=== Exec-in-Host-Mount-Namespace Health Check ===" +echo "Date: $(date)" +echo + +# Check namespace availability +echo "Checking namespace availability..." +if [ ! -e /proc/1/ns/mnt ]; then + echo "ERROR: Host mount namespace not available" + HEALTH_STATUS=1 +fi + +# Check privileges +echo "Checking privileges..." +if [ "$EUID" -ne 0 ]; then + echo "ERROR: Must run as root" + HEALTH_STATUS=1 +fi + +# Test namespace access +echo "Testing namespace access..." +if ! bootc exec-in-host-mount-namespace ls / > /dev/null 2>&1; then + echo "ERROR: Cannot access host namespace" + HEALTH_STATUS=1 +fi + +# Test command execution +echo "Testing command execution..." +if ! bootc exec-in-host-mount-namespace /bin/true > /dev/null 2>&1; then + echo "ERROR: Command execution failed" + HEALTH_STATUS=1 +fi + +# Report health status +if [ $HEALTH_STATUS -eq 0 ]; then + echo "Health check passed" +else + echo "Health check failed" +fi + +exit $HEALTH_STATUS +``` + +#### Alerting Script + +```bash +#!/bin/bash +# Alerting script + +# Send alert to monitoring system +send_alert() { + local severity=$1 + local message=$2 + + curl -X POST "https://monitoring.example.com/alerts" \ + -H "Content-Type: application/json" \ + -d "{ + \"service\": \"bootc-exec-in-host-mount-namespace\", + \"severity\": \"$severity\", + \"message\": \"$message\", + \"timestamp\": \"$(date -Iseconds)\" + }" +} + +# Check system health +if ! /usr/local/bin/bootc-exec-in-host-mount-namespace-health-check.sh; then + send_alert "critical" "Exec-in-host-mount-namespace system health check failed" +fi + +# Check namespace availability +if [ ! -e /proc/1/ns/mnt ]; then + send_alert "critical" "Host mount namespace not available" +fi + +# Check command execution +if ! bootc exec-in-host-mount-namespace /bin/true > /dev/null 2>&1; then + send_alert "warning" "Command execution in host namespace failed" +fi +``` + +## Best Practices + +### 1. Usage Guidelines + +- **Internal Use**: This is an internal command, not for direct user use +- **Container Context**: Use within container environments +- **Host Access**: Use when host mount namespace access is needed +- **Debugging**: Use for debugging and maintenance operations + +### 2. Security Considerations + +- **Privilege Requirements**: Ensure appropriate privileges +- **Namespace Access**: Verify namespace access permissions +- **Command Validation**: Validate commands before execution +- **Error Handling**: Implement proper error handling + +### 3. Performance Optimization + +- **Minimal Overhead**: Use only when necessary +- **Efficient Execution**: Use direct system calls +- **Resource Management**: Manage resources appropriately +- **Error Recovery**: Implement proper error recovery + +This comprehensive examples and troubleshooting guide provides practical solutions for common issues and advanced debugging techniques for the bootc exec-in-host-mount-namespace system. diff --git a/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-external-commands.md b/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-external-commands.md new file mode 100644 index 0000000..f63144c --- /dev/null +++ b/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-external-commands.md @@ -0,0 +1,910 @@ +# bootc exec-in-host-mount-namespace - External Commands Reference + +## Overview + +This document provides a comprehensive reference for all external commands used by `bootc exec-in-host-mount-namespace` operations. These commands are essential for understanding the dependencies and integration points of the exec-in-host-mount-namespace system. + +## Core Commands + +### bootc + +**Purpose**: Main bootc command for exec-in-host-mount-namespace operations +**Usage**: `bootc exec-in-host-mount-namespace [ARGS]...` +**Dependencies**: None (core command) + +#### Examples +```bash +# Execute command in host mount namespace +bootc exec-in-host-mount-namespace ls / + +# Execute with arguments +bootc exec-in-host-mount-namespace mount /dev/sda1 /mnt + +# Execute system command +bootc exec-in-host-mount-namespace systemctl status +``` + +## System Commands + +### setns + +**Purpose**: Change namespace membership +**Usage**: `setns [options...] [program [arguments...]]` +**Dependencies**: util-linux + +#### Examples +```bash +# Change to mount namespace +setns /proc/1/ns/mnt /bin/bash + +# Change to PID namespace +setns /proc/1/ns/pid /bin/bash + +# Change to network namespace +setns /proc/1/ns/net /bin/bash +``` + +### unshare + +**Purpose**: Run program in new namespaces +**Usage**: `unshare [options...] [program [arguments...]]` +**Dependencies**: util-linux + +#### Examples +```bash +# Create new mount namespace +unshare -m /bin/bash + +# Create new PID namespace +unshare -p /bin/bash + +# Create new network namespace +unshare -n /bin/bash + +# Create multiple namespaces +unshare -m -p -n /bin/bash +``` + +### nsenter + +**Purpose**: Enter namespaces +**Usage**: `nsenter [options...] [program [arguments...]]` +**Dependencies**: util-linux + +#### Examples +```bash +# Enter mount namespace +nsenter -m -t 1 /bin/bash + +# Enter PID namespace +nsenter -p -t 1 /bin/bash + +# Enter network namespace +nsenter -n -t 1 /bin/bash + +# Enter multiple namespaces +nsenter -m -p -n -t 1 /bin/bash +``` + +## Filesystem Commands + +### mount + +**Purpose**: Mount filesystems +**Usage**: `mount [options...] ` +**Dependencies**: util-linux + +#### Examples +```bash +# Mount filesystem +mount /dev/sda1 /mnt + +# Mount with options +mount -o ro,noexec /dev/sda1 /mnt + +# Mount bind +mount --bind /source /target + +# Mount tmpfs +mount -t tmpfs tmpfs /tmp +``` + +### umount + +**Purpose**: Unmount filesystems +**Usage**: `umount [options...] ` +**Dependencies**: util-linux + +#### Examples +```bash +# Unmount filesystem +umount /mnt + +# Force unmount +umount -f /mnt + +# Lazy unmount +umount -l /mnt + +# Unmount all +umount -a +``` + +### chroot + +**Purpose**: Change root directory +**Usage**: `chroot [options...] ` +**Dependencies**: coreutils + +#### Examples +```bash +# Change root +chroot /mnt /bin/bash + +# Change root with specific command +chroot /mnt /bin/ls + +# Change root with environment +chroot /mnt env -i /bin/bash +``` + +### chdir + +**Purpose**: Change working directory +**Usage**: `chdir ` +**Dependencies**: coreutils + +#### Examples +```bash +# Change to root directory +chdir / + +# Change to specific directory +chdir /var/lib/bootc + +# Change to home directory +chdir ~ +``` + +## Process Commands + +### exec + +**Purpose**: Replace current process +**Usage**: `exec [command [arguments...]]` +**Dependencies**: coreutils + +#### Examples +```bash +# Replace with new command +exec /bin/bash + +# Replace with command and arguments +exec /bin/ls -la / + +# Replace with shell +exec /bin/sh +``` + +### ps + +**Purpose**: Process status +**Usage**: `ps [options...]` +**Dependencies**: procps + +#### Examples +```bash +# Show all processes +ps aux + +# Show process tree +ps -ef + +# Show specific process +ps -p 1234 + +# Show processes by user +ps -u username +``` + +### kill + +**Purpose**: Send signals to processes +**Usage**: `kill [options...] ` +**Dependencies**: util-linux + +#### Examples +```bash +# Kill process +kill 1234 + +# Force kill process +kill -9 1234 + +# Send signal +kill -TERM 1234 + +# Kill by name +pkill process_name +``` + +## System Information Commands + +### uname + +**Purpose**: System information +**Usage**: `uname [options...]` +**Dependencies**: coreutils + +#### Examples +```bash +# Show system name +uname + +# Show all information +uname -a + +# Show kernel name +uname -s + +# Show kernel version +uname -r + +# Show machine type +uname -m +``` + +### hostname + +**Purpose**: Hostname operations +**Usage**: `hostname [options...]` +**Dependencies**: hostname + +#### Examples +```bash +# Show hostname +hostname + +# Show FQDN +hostname -f + +# Show short hostname +hostname -s + +# Show domain name +hostname -d +``` + +### lscpu + +**Purpose**: CPU information +**Usage**: `lscpu [options...]` +**Dependencies**: util-linux + +#### Examples +```bash +# Show CPU information +lscpu + +# Show in JSON format +lscpu -J + +# Show in extended format +lscpu -e + +# Show in parseable format +lscpu -p +``` + +### free + +**Purpose**: Memory information +**Usage**: `free [options...]` +**Dependencies**: procps + +#### Examples +```bash +# Show memory usage +free + +# Show in human readable format +free -h + +# Show in bytes +free -b + +# Show with total +free -t + +# Show with wide format +free -w +``` + +## File Commands + +### ls + +**Purpose**: List directory contents +**Usage**: `ls [options...] [file...]` +**Dependencies**: coreutils + +#### Examples +```bash +# List files +ls + +# List with details +ls -l + +# List all files +ls -a + +# List with human readable sizes +ls -lh + +# List with recursive +ls -R + +# List with sort by time +ls -lt +``` + +### find + +**Purpose**: Find files +**Usage**: `find [path...] [expression]` +**Dependencies**: findutils + +#### Examples +```bash +# Find files by name +find /path -name "*.txt" + +# Find files by type +find /path -type f + +# Find files by size +find /path -size +100M + +# Find files by modification time +find /path -mtime -7 + +# Find files by permissions +find /path -perm 644 +``` + +### stat + +**Purpose**: File status +**Usage**: `stat [options...] [file...]` +**Dependencies**: coreutils + +#### Examples +```bash +# Show file status +stat file.txt + +# Show in custom format +stat -c "%n %s %Y" file.txt + +# Show filesystem status +stat -f /path + +# Show with format +stat --format="%n: %s bytes" file.txt +``` + +## Storage Commands + +### df + +**Purpose**: Disk space usage +**Usage**: `df [options...] [file...]` +**Dependencies**: coreutils + +#### Examples +```bash +# Show disk usage +df -h + +# Show specific filesystem +df -h /var/lib/bootc + +# Show inode usage +df -i + +# Show all filesystems +df -a +``` + +### du + +**Purpose**: Directory space usage +**Usage**: `du [options...] [file...]` +**Dependencies**: coreutils + +#### Examples +```bash +# Show directory usage +du -h /var/lib/bootc + +# Show total usage +du -sh /var/lib/bootc + +# Show usage by subdirectory +du -h --max-depth=1 /var/lib/bootc + +# Show usage of all files +du -ah /var/lib/bootc +``` + +### lsblk + +**Purpose**: List block devices +**Usage**: `lsblk [options...]` +**Dependencies**: util-linux + +#### Examples +```bash +# List block devices +lsblk + +# Show device tree +lsblk -f + +# Show device sizes +lsblk -b + +# Show device types +lsblk -d +``` + +## Network Commands + +### curl + +**Purpose**: HTTP client for registry operations +**Usage**: `curl [options...] ` +**Dependencies**: curl + +#### Examples +```bash +# Download file +curl -O https://example.com/file.tar + +# Get HTTP headers +curl -I https://example.com + +# POST data +curl -X POST -d "data" https://example.com + +# With authentication +curl -u username:password https://example.com + +# With custom headers +curl -H "Authorization: Bearer token" https://example.com +``` + +### wget + +**Purpose**: HTTP client for downloading files +**Usage**: `wget [options...] ` +**Dependencies**: wget + +#### Examples +```bash +# Download file +wget https://example.com/file.tar + +# Download with progress +wget --progress=bar https://example.com/file.tar + +# Download recursively +wget -r https://example.com/ + +# Download with authentication +wget --user=username --password=password https://example.com +``` + +## Systemd Commands + +### systemctl + +**Purpose**: Systemd service management +**Usage**: `systemctl [options...]` +**Dependencies**: systemd + +#### Examples +```bash +# Check service status +systemctl status bootc-* + +# Start service +systemctl start bootc-* + +# Enable service +systemctl enable bootc-* + +# Reload systemd configuration +systemctl daemon-reload +``` + +### journalctl + +**Purpose**: Systemd journal viewing +**Usage**: `journalctl [options...]` +**Dependencies**: systemd + +#### Examples +```bash +# Show all logs +journalctl + +# Show logs for service +journalctl -u bootc-* + +# Show recent logs +journalctl -n 100 + +# Follow logs +journalctl -f + +# Show logs since time +journalctl --since "1 hour ago" + +# Show logs with priority +journalctl -p err +``` + +## Container Commands + +### podman + +**Purpose**: Container runtime +**Usage**: `podman [options...]` +**Dependencies**: podman + +#### Examples +```bash +# List containers +podman ps + +# List images +podman images + +# Pull image +podman pull quay.io/myorg/image:latest + +# Run container +podman run -it image:latest + +# Build image +podman build -t myimage:latest . + +# Inspect image +podman inspect image:latest +``` + +### docker + +**Purpose**: Alternative container runtime +**Usage**: `docker [options...]` +**Dependencies**: docker + +#### Examples +```bash +# List containers +docker ps + +# List images +docker images + +# Pull image +docker pull quay.io/myorg/image:latest + +# Run container +docker run -it image:latest + +# Build image +docker build -t myimage:latest . +``` + +## Bootloader Commands + +### grub-mkconfig + +**Purpose**: Generate GRUB configuration +**Usage**: `grub-mkconfig [options...]` +**Dependencies**: grub2 + +#### Examples +```bash +# Generate GRUB config +grub-mkconfig -o /boot/grub/grub.cfg + +# Generate with specific output +grub-mkconfig -o /boot/grub2/grub.cfg + +# Generate with verbose output +grub-mkconfig -v -o /boot/grub/grub.cfg +``` + +### grub-install + +**Purpose**: Install GRUB bootloader +**Usage**: `grub-install [options...] ` +**Dependencies**: grub2 + +#### Examples +```bash +# Install GRUB +grub-install /dev/sda + +# Install with specific directory +grub-install --boot-directory=/boot /dev/sda + +# Install with verbose output +grub-install -v /dev/sda +``` + +### efibootmgr + +**Purpose**: EFI boot manager +**Usage**: `efibootmgr [options...]` +**Dependencies**: efibootmgr + +#### Examples +```bash +# List boot entries +efibootmgr + +# Create boot entry +efibootmgr -c -d /dev/sda -p 1 -L "Bootc" -l /EFI/bootc/grubx64.efi + +# Delete boot entry +efibootmgr -b 0000 -B + +# Set boot order +efibootmgr -o 0000,0001,0002 +``` + +## Archive Commands + +### tar + +**Purpose**: Archive operations +**Usage**: `tar [options...] [file...]` +**Dependencies**: tar + +#### Examples +```bash +# Create archive +tar -cf archive.tar file1 file2 + +# Extract archive +tar -xf archive.tar + +# List archive contents +tar -tf archive.tar + +# Create compressed archive +tar -czf archive.tar.gz file1 file2 + +# Extract compressed archive +tar -xzf archive.tar.gz +``` + +### gzip + +**Purpose**: Compression +**Usage**: `gzip [options...] [file...]` +**Dependencies**: gzip + +#### Examples +```bash +# Compress file +gzip file.txt + +# Decompress file +gzip -d file.txt.gz + +# Compress with custom level +gzip -9 file.txt + +# Keep original file +gzip -k file.txt +``` + +## Monitoring Commands + +### top + +**Purpose**: Process monitoring +**Usage**: `top [options...]` +**Dependencies**: procps + +#### Examples +```bash +# Show processes +top + +# Show specific user +top -u username + +# Show specific process +top -p 1234 + +# Show with custom delay +top -d 5 + +# Show with custom sort +top -o %CPU +``` + +### htop + +**Purpose**: Interactive process monitoring +**Usage**: `htop [options...]` +**Dependencies**: htop + +#### Examples +```bash +# Show processes +htop + +# Show specific user +htop -u username + +# Show specific process +htop -p 1234 + +# Show with custom delay +htop -d 5 +``` + +### iotop + +**Purpose**: I/O monitoring +**Usage**: `iotop [options...]` +**Dependencies**: iotop + +#### Examples +```bash +# Show I/O usage +iotop + +# Show only processes doing I/O +iotop -o + +# Show with custom delay +iotop -d 5 + +# Show with custom refresh +iotop -n 10 +``` + +## Security Commands + +### openssl + +**Purpose**: SSL/TLS operations +**Usage**: `openssl [options...]` +**Dependencies**: openssl + +#### Examples +```bash +# Generate private key +openssl genrsa -out key.pem 2048 + +# Generate certificate +openssl req -new -x509 -key key.pem -out cert.pem + +# Verify certificate +openssl verify cert.pem + +# Check certificate details +openssl x509 -in cert.pem -text -noout + +# Generate hash +openssl dgst -sha256 file.txt +``` + +### gpg + +**Purpose**: GPG operations +**Usage**: `gpg [options...]` +**Dependencies**: gnupg + +#### Examples +```bash +# Generate key pair +gpg --gen-key + +# List keys +gpg --list-keys + +# Sign file +gpg --sign file.txt + +# Verify signature +gpg --verify file.txt.asc + +# Encrypt file +gpg --encrypt file.txt +``` + +## Development Commands + +### make + +**Purpose**: Build automation +**Usage**: `make [target...]` +**Dependencies**: make + +#### Examples +```bash +# Build project +make + +# Clean build +make clean + +# Install +make install + +# Run tests +make test + +# Update generated files +make update-generated +``` + +### cargo + +**Purpose**: Rust package manager +**Usage**: `cargo [options...]` +**Dependencies**: rust + +#### Examples +```bash +# Build project +cargo build + +# Run project +cargo run + +# Run tests +cargo test + +# Check code +cargo check + +# Update dependencies +cargo update +``` + +### git + +**Purpose**: Version control +**Usage**: `git [options...]` +**Dependencies**: git + +#### Examples +```bash +# Clone repository +git clone https://github.com/containers/bootc.git + +# Check status +git status + +# Add files +git add . + +# Commit changes +git commit -m "message" + +# Push changes +git push +``` + +This comprehensive reference covers all external commands used by the bootc exec-in-host-mount-namespace system, providing examples and usage patterns for each command. diff --git a/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-flowchart.md b/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-flowchart.md new file mode 100644 index 0000000..5c0bd42 --- /dev/null +++ b/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-flowchart.md @@ -0,0 +1,436 @@ +# bootc exec-in-host-mount-namespace - Process Flowchart + +## Overview + +This document provides a visual representation of the `bootc exec-in-host-mount-namespace` process flow, showing the decision points, operations, and system state changes involved in executing commands in the host mount namespace. + +## Main Process Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ bootc exec-in-host-mount-namespace โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Parse Command Arguments โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Parse command and arguments โ”‚ +โ”‚ โ€ข Validate arguments โ”‚ +โ”‚ โ€ข Check command availability โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Validate Prerequisites โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Check if command is provided โ”‚ +โ”‚ โ€ข Verify argument structure โ”‚ +โ”‚ โ€ข Validate command syntax โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Access Host Mount Namespace โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Open /proc/1/ns/mnt โ”‚ +โ”‚ โ€ข Get host mount namespace file descriptor โ”‚ +โ”‚ โ€ข Prepare for namespace switching โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Switch to Host Namespace โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Use setns system call โ”‚ +โ”‚ โ€ข Switch to host mount namespace โ”‚ +โ”‚ โ€ข Update process mount view โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Prepare Execution Environment โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Change to root directory โ”‚ +โ”‚ โ€ข Handle supermin workaround โ”‚ +โ”‚ โ€ข Set up execution context โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Execute Command โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Replace current process with target command โ”‚ +โ”‚ โ€ข Execute command with arguments โ”‚ +โ”‚ โ€ข Return execution result โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Detailed Process Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Command Parsing โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Split Arguments โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Argument Structure โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Command โ”‚ โ”‚ Arguments โ”‚ โ”‚ Validation โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ First Arg โ”‚โ”‚ โ”‚ โ”‚ Remaining โ”‚โ”‚ โ”‚ โ”‚ Check Args โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ (Command) โ”‚โ”‚ โ”‚ โ”‚ Arguments โ”‚โ”‚ โ”‚ โ”‚ Structure โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Namespace Access โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Open Host Namespace โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Open /proc/1/ns/mnt file โ”‚ +โ”‚ โ€ข Get file descriptor for host mount namespace โ”‚ +โ”‚ โ€ข Prepare for setns operation โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Namespace Switching โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ setns Operation โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ move_into_link_name_space โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Use rustix::thread::move_into_link_name_space โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Specify Mount namespace type โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Switch to host mount namespace โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Environment Setup โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Directory Operations โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Change to root directory (chdir("/")) โ”‚ +โ”‚ โ€ข Check for supermin workaround conditions โ”‚ +โ”‚ โ€ข Handle chroot if necessary โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Supermin Workaround โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Check Conditions โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Normal Path โ”‚ โ”‚ Supermin Path โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ /usr exists โ”‚โ”‚ โ”‚ โ”‚ /usr doesn't exist โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Continue โ”‚โ”‚ โ”‚ โ”‚ /root/usr exists โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ normally โ”‚โ”‚ โ”‚ โ”‚ chroot("/root") โ”‚โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Command Execution โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Process Replacement โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Create Command with target command and arguments โ”‚ +โ”‚ โ€ข Set process name (arg0) โ”‚ +โ”‚ โ€ข Execute command (exec) โ”‚ +โ”‚ โ€ข Replace current process โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Namespace Operations Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Namespace Operations โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Current Namespace โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Container/Isolated Namespace โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Limited filesystem view โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Isolated mount points โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Restricted access โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ setns Operation โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Open /proc/1/ns/mnt โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Get file descriptor โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Call setns system call โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Switch to host namespace โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Host Namespace โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Full filesystem view โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Host mount points โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Complete access โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Error Handling Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Error Detection โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Error Classification โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Argument โ”‚ โ”‚ Namespace โ”‚ โ”‚ Execution โ”‚ โ”‚ +โ”‚ โ”‚ Errors โ”‚ โ”‚ Errors โ”‚ โ”‚ Errors โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Missing Cmd โ”‚ โ”‚ โ€ข Access Denied โ”‚ โ”‚ โ€ข Command Not โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Invalid Args โ”‚ โ”‚ โ€ข Namespace Not โ”‚ โ”‚ Found โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Bad Syntax โ”‚ โ”‚ Available โ”‚ โ”‚ โ€ข Permission โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ€ข setns Failed โ”‚ โ”‚ Denied โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Error Response โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Display error message โ”‚ +โ”‚ โ€ข Provide context information โ”‚ +โ”‚ โ€ข Suggest remediation steps โ”‚ +โ”‚ โ€ข Return appropriate exit code โ”‚ +โ”‚ โ€ข Log error details โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## System State Transitions + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ System States โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Initial State โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Container/Isolated Environment โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Limited filesystem access โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Isolated mount namespace โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Restricted system view โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Execute Command โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Parse arguments โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Access host namespace โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Switch namespaces โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Final State โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Host mount namespace access โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Full filesystem view โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Command executed in host context โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Command Execution Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Command Execution โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Prepare Command โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Create Command struct โ”‚ +โ”‚ โ€ข Set command name โ”‚ +โ”‚ โ€ข Set arguments โ”‚ +โ”‚ โ€ข Set process name (arg0) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Execute Command โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Use exec() to replace current process โ”‚ +โ”‚ โ€ข Execute command with arguments โ”‚ +โ”‚ โ€ข Return execution result โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Process Replacement โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Current process is replaced โ”‚ +โ”‚ โ€ข Target command becomes new process โ”‚ +โ”‚ โ€ข Execution continues in host namespace โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Helper Function Flow + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Helper Functions โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ run_in_host_mountns โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Create Command for host mount namespace execution โ”‚ +โ”‚ โ€ข Set executable path โ”‚ +โ”‚ โ€ข Add exec-in-host-mount-namespace argument โ”‚ +โ”‚ โ€ข Return prepared Command โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ ensure_self_unshared_mount_namespace โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Check if already in mount namespace โ”‚ +โ”‚ โ€ข Check if root user โ”‚ +โ”‚ โ€ข Unshare mount namespace if needed โ”‚ +โ”‚ โ€ข Re-exec with unshared namespace โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +## Use Case Flows + +### 1. Container Operations + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Container Operations โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Container Environment โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Limited filesystem view โ”‚ +โ”‚ โ€ข Isolated mount namespace โ”‚ +โ”‚ โ€ข Restricted access to host โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Execute in Host Namespace โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Switch to host mount namespace โ”‚ +โ”‚ โ€ข Access host filesystem โ”‚ +โ”‚ โ€ข Perform host operations โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### 2. Installation Support + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Installation Support โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Installation Process โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Running in container context โ”‚ +โ”‚ โ€ข Need access to host filesystem โ”‚ +โ”‚ โ€ข Perform installation operations โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Host Filesystem Access โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Execute commands in host namespace โ”‚ +โ”‚ โ€ข Access host filesystem โ”‚ +โ”‚ โ€ข Complete installation โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### 3. Debugging and Maintenance + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Debugging and Maintenance โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Debug Environment โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Isolated debugging environment โ”‚ +โ”‚ โ€ข Need access to host system โ”‚ +โ”‚ โ€ข Perform debugging operations โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Host System Access โ”‚ +โ”‚ โ”‚ +โ”‚ โ€ข Execute debugging commands in host namespace โ”‚ +โ”‚ โ”‚ โ€ข Check host filesystem โ”‚ +โ”‚ โ”‚ โ€ข View host processes โ”‚ +โ”‚ โ”‚ โ€ข Monitor host system โ”‚ +โ”‚ โ€ข Complete debugging operations โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +This flowchart provides a comprehensive visual representation of the bootc exec-in-host-mount-namespace process, showing all decision points, operations, and state transitions involved in executing commands in the host mount namespace. diff --git a/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-quick-reference.md b/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-quick-reference.md new file mode 100644 index 0000000..4bfb314 --- /dev/null +++ b/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-quick-reference.md @@ -0,0 +1,290 @@ +# bootc exec-in-host-mount-namespace - Quick Reference + +## Command Summary + +| Command | Purpose | Usage | +|---------|---------|-------| +| `exec-in-host-mount-namespace` | Execute command in host mount namespace | `bootc exec-in-host-mount-namespace [ARGS]...` | + +## Quick Commands + +### Basic Operations +```bash +# Execute command in host mount namespace +bootc exec-in-host-mount-namespace ls / + +# Execute with arguments +bootc exec-in-host-mount-namespace mount /dev/sda1 /mnt + +# Execute system command +bootc exec-in-host-mount-namespace systemctl status +``` + +### System Operations +```bash +# Check host filesystem +bootc exec-in-host-mount-namespace df -h + +# View host processes +bootc exec-in-host-mount-namespace ps aux + +# Check host system status +bootc exec-in-host-mount-namespace systemctl status +``` + +### Installation Operations +```bash +# Create directories in host filesystem +bootc exec-in-host-mount-namespace mkdir -p /var/lib/bootc + +# Copy files to host filesystem +bootc exec-in-host-mount-namespace cp /source/file /host/destination/ + +# Set permissions +bootc exec-in-host-mount-namespace chmod 644 /host/file +``` + +## Common Options + +| Option | Purpose | Example | +|--------|---------|---------| +| `--help` | Show help | `bootc exec-in-host-mount-namespace --help` | +| `--verbose` | Verbose output | `bootc exec-in-host-mount-namespace -v ls /` | +| `--quiet` | Quiet output | `bootc exec-in-host-mount-namespace -q ls /` | + +## Error Codes + +| Code | Meaning | Solution | +|------|---------|----------| +| 1 | General error | Check logs for details | +| 2 | Missing command | Provide command to execute | +| 3 | Namespace access error | Check /proc/1/ns/mnt exists | +| 4 | setns error | Run as root | +| 5 | Command not found | Use full path to command | + +## Common Issues + +### Missing Command +```bash +# Error: Missing command +# Solution: Provide a command +bootc exec-in-host-mount-namespace ls / + +# Or use a shell +bootc exec-in-host-mount-namespace /bin/bash +``` + +### Namespace Access Error +```bash +# Error: open pid1 mountns: No such file or directory +# Solution: Check if /proc/1/ns/mnt exists +ls -la /proc/1/ns/mnt + +# Run as root +sudo bootc exec-in-host-mount-namespace ls / +``` + +### setns Error +```bash +# Error: setns: Operation not permitted +# Solution: Run as root +sudo bootc exec-in-host-mount-namespace ls / + +# Check capabilities +getcap /usr/bin/bootc +``` + +### Command Not Found +```bash +# Error: exec: command not found +# Solution: Use full path +bootc exec-in-host-mount-namespace /bin/ls / + +# Check command availability +bootc exec-in-host-mount-namespace which ls +``` + +## Environment Variables + +| Variable | Purpose | Default | +|----------|---------|---------| +| `RUST_LOG` | Log level | `info` | +| `BOOTC_DEBUG` | Debug mode | `false` | +| `BOOTC_CONFIG` | Config file | `/etc/bootc/config.toml` | + +## Configuration Files + +| File | Purpose | Location | +|------|---------|----------| +| Main config | Bootc configuration | `/etc/bootc/config.toml` | +| Namespace info | Namespace information | `/proc/1/ns/mnt` | +| Process info | Process information | `/proc/self/ns/mnt` | + +## Log Files + +| File | Purpose | Location | +|------|---------|----------| +| System logs | System messages | `/var/log/messages` | +| Journal logs | Systemd journal | `journalctl -u bootc-*` | +| Bootc logs | Bootc specific | `/var/log/bootc/` | + +## Performance Tips + +### Optimize Operations +```bash +# Check system load +uptime + +# Check memory usage +free -h + +# Check namespace overhead +time bootc exec-in-host-mount-namespace /bin/true +time /bin/true +``` + +### Monitor System +```bash +# Check namespace availability +ls -la /proc/1/ns/mnt + +# Check namespace differences +diff /proc/1/ns/mnt /proc/self/ns/mnt + +# Check system performance +bootc exec-in-host-mount-namespace top -bn1 | head -20 +``` + +## Security Considerations + +### Root Privileges +- All exec-in-host-mount-namespace commands require root privileges +- Use `sudo` or switch to root user +- Check current user with `whoami` + +### Namespace Access +- Command accesses host mount namespace through `/proc/1/ns/mnt` +- Requires appropriate privileges for namespace switching +- Uses `setns` system call for namespace switching + +### Process Isolation +- Command executes in host mount namespace +- Current process is replaced with target command +- Provides access to host filesystem view + +## Best Practices + +### Regular Operations +- Use only when host mount namespace access is needed +- Check command availability before execution +- Implement proper error handling +- Monitor system performance + +### Development +- Use in container environments +- Test commands before production use +- Document procedures +- Monitor system health + +### Production +- Set up monitoring +- Configure alerts +- Regular testing +- Document procedures + +## Troubleshooting Steps + +1. **Check command availability** + ```bash + bootc exec-in-host-mount-namespace which + ``` + +2. **Check namespace availability** + ```bash + ls -la /proc/1/ns/mnt + ``` + +3. **Check privileges** + ```bash + whoami + sudo bootc exec-in-host-mount-namespace + ``` + +4. **Check logs** + ```bash + journalctl -u bootc-* --since "1 hour ago" + tail -f /var/log/bootc/main.log + ``` + +5. **Test command execution** + ```bash + bootc exec-in-host-mount-namespace /bin/true + ``` + +## Quick Scripts + +### Health Check +```bash +#!/bin/bash +bootc exec-in-host-mount-namespace /bin/true && echo "System healthy" +``` + +### Namespace Test +```bash +#!/bin/bash +bootc exec-in-host-mount-namespace ls / && echo "Namespace access OK" +``` + +### Command Test +```bash +#!/bin/bash +bootc exec-in-host-mount-namespace which "$1" && echo "Command available" +``` + +### System Check +```bash +#!/bin/bash +bootc exec-in-host-mount-namespace uname -a && echo "System check OK" +``` + +## Integration Examples + +### Systemd Service +```bash +# Create service file +cat > /etc/systemd/system/bootc-exec-in-host-mount-namespace.service << EOF +[Unit] +Description=Bootc Exec in Host Mount Namespace Service +After=multi-user.target + +[Service] +Type=oneshot +ExecStart=/usr/local/bin/bootc-exec-in-host-mount-namespace-script.sh +User=root +Group=root + +[Install] +WantedBy=multi-user.target +EOF + +# Enable service +systemctl daemon-reload +systemctl enable bootc-exec-in-host-mount-namespace.service +``` + +### Cron Job +```bash +# Add to crontab +echo "0 2 * * * /usr/local/bin/bootc-exec-in-host-mount-namespace-maintenance.sh" | crontab - +``` + +### Monitoring +```bash +# Check system health +if ! bootc exec-in-host-mount-namespace /bin/true > /dev/null 2>&1; then + echo "WARNING: Exec-in-host-mount-namespace failed" + # Send alert +fi +``` + +This quick reference provides essential information for using the bootc exec-in-host-mount-namespace system effectively. diff --git a/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-technical-guide.md b/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-technical-guide.md new file mode 100644 index 0000000..0872cff --- /dev/null +++ b/exec-in-host-mount-namespace/bootc-exec-in-host-mount-namespace-technical-guide.md @@ -0,0 +1,492 @@ +# bootc exec-in-host-mount-namespace - Technical Guide + +## Overview + +`bootc exec-in-host-mount-namespace` is a hidden command that executes a given command in the host mount namespace. This is a critical low-level operation used internally by bootc for system operations that need to access the host's mount namespace from within a container or isolated environment. + +## Purpose + +The exec-in-host-mount-namespace command serves several critical functions: + +1. **Namespace Isolation**: Execute commands in the host mount namespace from within containers +2. **System Operations**: Perform operations that require access to the host's filesystem view +3. **Installation Support**: Support installation operations that need host mount access +4. **Debugging**: Provide access to host mount namespace for debugging and maintenance + +## Command Structure + +```rust +/// Execute the given command in the host mount namespace +#[clap(hide = true)] +ExecInHostMountNamespace { + #[clap(trailing_var_arg = true, allow_hyphen_values = true)] + args: Vec, +} +``` + +## Core Functionality + +### Purpose + +The command executes a specified command in the host mount namespace, allowing operations that need to access the host's filesystem view from within a container or isolated environment. + +### Usage + +```bash +bootc exec-in-host-mount-namespace [ARGS]... +``` + +### Implementation + +```rust +#[context("Re-exec in host mountns")] +pub(crate) fn exec_in_host_mountns(args: &[std::ffi::OsString]) -> Result<()> { + let (cmd, args) = args + .split_first() + .ok_or_else(|| anyhow::anyhow!("Missing command"))?; + tracing::trace!("{cmd:?} {args:?}"); + + // Open the host mount namespace + let pid1mountns = std::fs::File::open("/proc/1/ns/mnt").context("open pid1 mountns")?; + + // Move into the host mount namespace + rustix::thread::move_into_link_name_space( + pid1mountns.as_fd(), + Some(rustix::thread::LinkNameSpaceType::Mount), + ) + .context("setns")?; + + // Change to root directory + rustix::process::chdir("/").context("chdir")?; + + // Work around supermin doing chroot() and not pivot_root + if !Utf8Path::new("/usr").try_exists().context("/usr")? + && Utf8Path::new("/root/usr") + .try_exists() + .context("/root/usr")? + { + tracing::debug!("Using supermin workaround"); + rustix::process::chroot("/root").context("chroot")?; + } + + // Execute the command + Err(Command::new(cmd).args(args).arg0(bootc_utils::NAME).exec()).context("exec")? +} +``` + +## Technical Details + +### 1. Mount Namespace Operations + +The command uses Linux mount namespace operations to switch to the host's mount namespace: + +```rust +// Open the host mount namespace (PID 1) +let pid1mountns = std::fs::File::open("/proc/1/ns/mnt").context("open pid1 mountns")?; + +// Move into the host mount namespace +rustix::thread::move_into_link_name_space( + pid1mountns.as_fd(), + Some(rustix::thread::LinkNameSpaceType::Mount), +) +.context("setns")?; +``` + +### 2. Directory Operations + +After switching namespaces, the command ensures proper directory context: + +```rust +// Change to root directory +rustix::process::chdir("/").context("chdir")?; + +// Work around supermin doing chroot() and not pivot_root +if !Utf8Path::new("/usr").try_exists().context("/usr")? + && Utf8Path::new("/root/usr") + .try_exists() + .context("/root/usr")? +{ + tracing::debug!("Using supermin workaround"); + rustix::process::chroot("/root").context("chroot")?; +} +``` + +### 3. Command Execution + +The command executes the specified command with proper argument handling: + +```rust +// Execute the command +Err(Command::new(cmd).args(args).arg0(bootc_utils::NAME).exec()).context("exec")? +``` + +## Command Routing + +The command is routed through the main CLI dispatcher: + +```rust +Opt::ExecInHostMountNamespace { args } => { + crate::install::exec_in_host_mountns(args.as_slice()) +} +``` + +## Helper Functions + +### 1. run_in_host_mountns + +A helper function to create a command that will execute in the host mount namespace: + +```rust +/// Run a command in the host mount namespace +pub(crate) fn run_in_host_mountns(cmd: &str) -> Result { + let mut c = Command::new(bootc_utils::reexec::executable_path()?); + c.lifecycle_bind() + .args(["exec-in-host-mount-namespace", cmd]); + Ok(c) +} +``` + +### 2. ensure_self_unshared_mount_namespace + +A function to ensure the process is in an unshared mount namespace: + +```rust +#[context("Ensuring mountns")] +pub(crate) fn ensure_self_unshared_mount_namespace() -> Result<()> { + let uid = rustix::process::getuid(); + if !uid.is_root() { + tracing::debug!("Not root, assuming no need to unshare"); + return Ok(()); + } + + let recurse_env = "_ostree_unshared"; + let ns_pid1 = std::fs::read_link("/proc/1/ns/mnt").context("Reading /proc/1/ns/mnt")?; + let ns_self = std::fs::read_link("/proc/self/ns/mnt").context("Reading /proc/self/ns/mnt")?; + + // If we already appear to be in a mount namespace, or we're already pid1, we're done + if ns_pid1 != ns_self { + tracing::debug!("Already in a mount namespace"); + return Ok(()); + } + + if std::env::var_os(recurse_env).is_some() { + let am_pid1 = rustix::process::getpid().is_init(); + if am_pid1 { + tracing::debug!("We are pid 1"); + return Ok(()); + } else { + anyhow::bail!("Failed to unshare mount namespace"); + } + } + + bootc_utils::reexec::reexec_with_guardenv(recurse_env, &["unshare", "-m", "--"]) +} +``` + +## Use Cases + +### 1. Container Operations + +When running inside a container, this command allows access to the host's mount namespace: + +```bash +# Execute a command in the host mount namespace +bootc exec-in-host-mount-namespace ls /host/path + +# Mount something in the host namespace +bootc exec-in-host-mount-namespace mount /dev/sda1 /mnt +``` + +### 2. Installation Support + +During installation operations, this command provides access to the host filesystem: + +```bash +# Access host filesystem during installation +bootc exec-in-host-mount-namespace mkdir -p /host/var/lib/bootc + +# Copy files to host filesystem +bootc exec-in-host-mount-namespace cp /source/file /host/destination/ +``` + +### 3. Debugging and Maintenance + +For debugging and maintenance operations that need host access: + +```bash +# Check host filesystem +bootc exec-in-host-mount-namespace df -h + +# View host processes +bootc exec-in-host-mount-namespace ps aux + +# Check host system status +bootc exec-in-host-mount-namespace systemctl status +``` + +### 4. System Integration + +For system integration operations that require host mount namespace access: + +```bash +# Update host bootloader +bootc exec-in-host-mount-namespace grub-mkconfig -o /boot/grub/grub.cfg + +# Update host initramfs +bootc exec-in-host-mount-namespace update-initramfs -u +``` + +## Technical Implementation + +### 1. Namespace Switching + +The command uses the `setns` system call to switch to the host mount namespace: + +```rust +rustix::thread::move_into_link_name_space( + pid1mountns.as_fd(), + Some(rustix::thread::LinkNameSpaceType::Mount), +) +.context("setns")?; +``` + +### 2. Process Execution + +The command uses `exec` to replace the current process with the target command: + +```rust +Err(Command::new(cmd).args(args).arg0(bootc_utils::NAME).exec()).context("exec")? +``` + +### 3. Error Handling + +Comprehensive error handling with context: + +```rust +#[context("Re-exec in host mountns")] +pub(crate) fn exec_in_host_mountns(args: &[std::ffi::OsString]) -> Result<()> { + // Implementation with automatic error context +} +``` + +## Security Considerations + +### 1. Privilege Requirements + +The command requires appropriate privileges to access mount namespaces: + +```rust +let uid = rustix::process::getuid(); +if !uid.is_root() { + tracing::debug!("Not root, assuming no need to unshare"); + return Ok(()); +} +``` + +### 2. Namespace Access + +The command accesses the host mount namespace through `/proc/1/ns/mnt`: + +```rust +let pid1mountns = std::fs::File::open("/proc/1/ns/mnt").context("open pid1 mountns")?; +``` + +### 3. Process Isolation + +The command executes in a different mount namespace, which provides isolation: + +- **Mount Isolation**: Commands run in the host mount namespace +- **Process Replacement**: The current process is replaced with the target command +- **Namespace Switching**: Uses `setns` to switch mount namespaces + +## Performance Characteristics + +### 1. Execution Time + +- **Fast**: Minimal overhead for namespace switching +- **Atomic**: Single atomic operation +- **Efficient**: Direct system call usage + +### 2. Resource Usage + +- **Low CPU**: Minimal CPU usage +- **Low Memory**: Minimal memory usage +- **Namespace Overhead**: Small overhead for namespace operations + +### 3. System Impact + +- **Namespace Switch**: Changes mount namespace +- **Process Replacement**: Replaces current process +- **Host Access**: Provides access to host filesystem + +## Integration Points + +### 1. Installation System + +The command is used by the installation system for host operations: + +```rust +// Used during installation +pub(crate) fn run_in_host_mountns(cmd: &str) -> Result { + let mut c = Command::new(bootc_utils::reexec::executable_path()?); + c.lifecycle_bind() + .args(["exec-in-host-mount-namespace", cmd]); + Ok(c) +} +``` + +### 2. Mount Namespace Management + +The command integrates with mount namespace management: + +```rust +// Ensure unshared mount namespace +ensure_self_unshared_mount_namespace()?; +``` + +### 3. Container Operations + +The command supports container operations that need host access: + +```rust +// Used in container contexts +if !external_source && std::env::var_os("BOOTC_SKIP_UNSHARE").is_none() { + super::cli::ensure_self_unshared_mount_namespace()?; +} +``` + +## Error Handling + +### 1. Common Error Scenarios + +#### Missing Command +```rust +let (cmd, args) = args + .split_first() + .ok_or_else(|| anyhow::anyhow!("Missing command"))?; +``` + +#### Namespace Access Error +```rust +let pid1mountns = std::fs::File::open("/proc/1/ns/mnt").context("open pid1 mountns")?; +``` + +#### Namespace Switch Error +```rust +rustix::thread::move_into_link_name_space( + pid1mountns.as_fd(), + Some(rustix::thread::LinkNameSpaceType::Mount), +) +.context("setns")?; +``` + +### 2. Error Recovery + +The command provides comprehensive error context: + +```rust +#[context("Re-exec in host mountns")] +pub(crate) fn exec_in_host_mountns(args: &[std::ffi::OsString]) -> Result<()> { + // Implementation with automatic error context +} +``` + +## Testing and Validation + +### 1. Unit Tests + +```rust +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_exec_in_host_mountns() { + // Test command execution + let args = vec!["ls".into(), "/".into()]; + let result = exec_in_host_mountns(&args); + // Verify result + } +} +``` + +### 2. Integration Tests + +```rust +#[tokio::test] +async fn test_exec_in_host_mountns_integration() { + // Test namespace switching + let test_env = TestEnvironment::new().await.unwrap(); + + // Test command execution in host namespace + let result = test_env.run_command("bootc", &["exec-in-host-mount-namespace", "ls", "/"]).await; + assert!(result.is_ok()); +} +``` + +## Best Practices + +### 1. Usage Guidelines + +- **Internal Use**: This is an internal command, not for direct user use +- **Container Context**: Use within container environments +- **Host Access**: Use when host mount namespace access is needed +- **Debugging**: Use for debugging and maintenance operations + +### 2. Security Considerations + +- **Privilege Requirements**: Ensure appropriate privileges +- **Namespace Access**: Verify namespace access permissions +- **Command Validation**: Validate commands before execution +- **Error Handling**: Implement proper error handling + +### 3. Performance Optimization + +- **Minimal Overhead**: Use only when necessary +- **Efficient Execution**: Use direct system calls +- **Resource Management**: Manage resources appropriately +- **Error Recovery**: Implement proper error recovery + +## Future Enhancements + +### 1. Additional Namespace Support + +Potential support for other namespaces: + +```rust +pub(crate) enum NamespaceType { + Mount, + PID, + Network, + User, + IPC, + UTS, + Cgroup, +} +``` + +### 2. Enhanced Security + +Enhanced security features: + +```rust +pub(crate) struct SecurityOptions { + pub drop_capabilities: bool, + pub restrict_filesystem: bool, + pub sandbox_command: bool, +} +``` + +### 3. Monitoring and Logging + +Enhanced monitoring and logging: + +```rust +pub(crate) struct ExecutionOptions { + pub log_execution: bool, + pub monitor_resources: bool, + pub track_namespace_changes: bool, +} +``` + +This technical guide provides comprehensive understanding of the bootc exec-in-host-mount-namespace system's functionality, implementation, and usage patterns. diff --git a/image/bootc-image-external-commands.md b/image/bootc-image-external-commands.md new file mode 100644 index 0000000..7ee7322 --- /dev/null +++ b/image/bootc-image-external-commands.md @@ -0,0 +1,1312 @@ +# bootc image - External Commands Reference + +## Overview + +This document provides a comprehensive reference for all external commands used by `bootc image` operations. These commands are essential for understanding the dependencies and integration points of the bootc image system. + +## Core Commands + +### bootc + +**Purpose**: Main bootc command for image operations +**Usage**: `bootc image [options...]` +**Dependencies**: None (core command) + +#### Subcommands +- `bootc image list` - List images in bootc storage +- `bootc image copy-to-storage` - Copy images to containers-storage +- `bootc image pull-from-default-storage` - Pull images from default storage +- `bootc image cmd` - Wrapper for podman image commands + +#### Examples +```bash +# List all images +bootc image list + +# List host images only +bootc image list --type=host + +# List in JSON format +bootc image list --format=json + +# Copy current image to containers-storage +bootc image copy-to-storage + +# Copy specific image +bootc image copy-to-storage --source=quay.io/myorg/debian-bootc:v2.0 + +# Pull image from default storage +bootc image pull-from-default-storage quay.io/myorg/debian-bootc:v2.0 +``` + +### podman + +**Purpose**: Container runtime and image management +**Usage**: `podman image [options...]` +**Dependencies**: podman package, containers-storage + +#### Image Subcommands +- `podman image list` - List images +- `podman image build` - Build images +- `podman image pull` - Pull images +- `podman image push` - Push images +- `podman image tag` - Tag images +- `podman image inspect` - Inspect images +- `podman image exists` - Check if image exists +- `podman image prune` - Remove unused images +- `podman image rmi` - Remove images + +#### Examples +```bash +# List all images +podman image list + +# Build image +podman image build -t myimage:latest . + +# Pull image +podman image pull quay.io/myorg/debian-bootc:v2.0 + +# Push image +podman image push myimage:latest + +# Tag image +podman image tag myimage:latest localhost/myimage:latest + +# Inspect image +podman image inspect myimage:latest + +# Check if image exists +podman image exists myimage:latest + +# Remove unused images +podman image prune -a + +# Remove specific image +podman image rmi myimage:latest +``` + +#### Storage Configuration +```bash +# Check podman info +podman info + +# Check storage configuration +podman info --format=json | jq '.store' + +# Check storage root +podman info --format=json | jq '.store.graphRoot' + +# Check run root +podman info --format=json | jq '.store.runRoot' +``` + +## Storage Commands + +### ostree + +**Purpose**: OSTree repository operations +**Usage**: `ostree [options...]` +**Dependencies**: ostree package + +#### Repository Commands +- `ostree log` - Show commit log +- `ostree show` - Show commit details +- `ostree refs` - List references +- `ostree ls` - List repository contents +- `ostree cat` - Show file contents +- `ostree checkout` - Checkout files +- `ostree admin status` - Show admin status +- `ostree admin pin` - Pin deployments +- `ostree admin unpin` - Unpin deployments + +#### Examples +```bash +# Show repository status +ostree admin status + +# List references +ostree refs + +# Show commit details +ostree show + +# List repository contents +ostree ls + +# Show file contents +ostree cat /path/to/file + +# Checkout files +ostree checkout /path/to/destination +``` + +### containers-storage + +**Purpose**: Container storage management +**Usage**: `containers-storage [options...]` +**Dependencies**: containers-storage package + +#### Storage Commands +- `containers-storage list` - List storage contents +- `containers-storage info` - Show storage information +- `containers-storage prune` - Clean up storage +- `containers-storage gc` - Garbage collect + +#### Examples +```bash +# List storage contents +containers-storage list + +# Show storage information +containers-storage info + +# Clean up storage +containers-storage prune + +# Garbage collect +containers-storage gc +``` + +## System Commands + +### systemctl + +**Purpose**: Systemd service management +**Usage**: `systemctl [options...]` +**Dependencies**: systemd + +#### Service Commands +- `systemctl status` - Show service status +- `systemctl start` - Start service +- `systemctl stop` - Stop service +- `systemctl restart` - Restart service +- `systemctl enable` - Enable service +- `systemctl disable` - Disable service +- `systemctl reload` - Reload service + +#### Examples +```bash +# Check service status +systemctl status bootc + +# Start service +systemctl start bootc + +# Stop service +systemctl stop bootc + +# Restart service +systemctl restart bootc + +# Enable service +systemctl enable bootc + +# Disable service +systemctl disable bootc +``` + +### mount + +**Purpose**: Filesystem mounting +**Usage**: `mount [options...] ` +**Dependencies**: util-linux + +#### Mount Commands +- `mount` - Mount filesystem +- `umount` - Unmount filesystem +- `mountpoint` - Check if directory is mountpoint +- `findmnt` - Find mounted filesystems + +#### Examples +```bash +# Mount filesystem +mount /dev/sda1 /mnt + +# Unmount filesystem +umount /mnt + +# Check mountpoint +mountpoint /mnt + +# Find mounted filesystems +findmnt + +# Find specific mount +findmnt /mnt +``` + +### df + +**Purpose**: Disk space usage +**Usage**: `df [options...] [file...]` +**Dependencies**: coreutils + +#### Examples +```bash +# Show disk usage +df -h + +# Show specific filesystem +df -h /var/lib/bootc + +# Show inode usage +df -i + +# Show all filesystems +df -a +``` + +### du + +**Purpose**: Directory space usage +**Usage**: `du [options...] [file...]` +**Dependencies**: coreutils + +#### Examples +```bash +# Show directory usage +du -h /var/lib/bootc + +# Show total usage +du -sh /var/lib/bootc + +# Show usage by subdirectory +du -h --max-depth=1 /var/lib/bootc + +# Show usage of all files +du -ah /var/lib/bootc +``` + +## Network Commands + +### curl + +**Purpose**: HTTP client for registry operations +**Usage**: `curl [options...] ` +**Dependencies**: curl + +#### Examples +```bash +# Download file +curl -O https://example.com/file.tar + +# Get HTTP headers +curl -I https://example.com + +# POST data +curl -X POST -d "data" https://example.com + +# With authentication +curl -u username:password https://example.com + +# With custom headers +curl -H "Authorization: Bearer token" https://example.com +``` + +### wget + +**Purpose**: HTTP client for downloading files +**Usage**: `wget [options...] ` +**Dependencies**: wget + +#### Examples +```bash +# Download file +wget https://example.com/file.tar + +# Download with progress +wget --progress=bar https://example.com/file.tar + +# Download recursively +wget -r https://example.com/ + +# Download with authentication +wget --user=username --password=password https://example.com +``` + +### ping + +**Purpose**: Network connectivity testing +**Usage**: `ping [options...] ` +**Dependencies**: iputils + +#### Examples +```bash +# Ping host +ping example.com + +# Ping with count +ping -c 4 example.com + +# Ping with timeout +ping -W 5 example.com + +# Ping IPv6 +ping6 example.com +``` + +## Data Processing Commands + +### jq + +**Purpose**: JSON processing +**Usage**: `jq [options...] [file...]` +**Dependencies**: jq + +#### Examples +```bash +# Pretty print JSON +echo '{"key":"value"}' | jq . + +# Extract value +echo '{"key":"value"}' | jq '.key' + +# Filter array +echo '[{"name":"a"},{"name":"b"}]' | jq '.[] | select(.name == "a")' + +# Transform data +echo '{"key":"value"}' | jq '{newkey: .key}' + +# Read from file +jq '.key' file.json +``` + +### yq + +**Purpose**: YAML processing +**Usage**: `yq [options...] [file...]` +**Dependencies**: yq + +#### Examples +```bash +# Pretty print YAML +yq eval '.' file.yaml + +# Extract value +yq eval '.key' file.yaml + +# Set value +yq eval '.key = "newvalue"' file.yaml + +# Delete key +yq eval 'del(.key)' file.yaml + +# Convert to JSON +yq eval -o=json file.yaml +``` + +### grep + +**Purpose**: Text searching +**Usage**: `grep [options...] [file...]` +**Dependencies**: grep + +#### Examples +```bash +# Search in file +grep "pattern" file.txt + +# Search recursively +grep -r "pattern" /path/to/dir + +# Case insensitive +grep -i "pattern" file.txt + +# Show line numbers +grep -n "pattern" file.txt + +# Show context +grep -C 3 "pattern" file.txt +``` + +### sed + +**Purpose**: Text editing +**Usage**: `sed [options...]