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
This commit is contained in:
robojerk
commit
526f1c1afd
67 changed files with 34174 additions and 0 deletions
3
.gitmodules
vendored
Normal file
3
.gitmodules
vendored
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
[submodule "bootc"]
|
||||
path = bootc
|
||||
url = https://github.com/containers/bootc.git
|
||||
270
README.md
Normal file
270
README.md
Normal file
|
|
@ -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/)
|
||||
1
bootc
Submodule
1
bootc
Submodule
|
|
@ -0,0 +1 @@
|
|||
Subproject commit 8ac9eae698b74aa26dbc3e62cf9d34749d2e70e3
|
||||
1162
building/base-images-wo-bootc.md
Normal file
1162
building/base-images-wo-bootc.md
Normal file
File diff suppressed because it is too large
Load diff
471
building/base-images.md
Normal file
471
building/base-images.md
Normal file
|
|
@ -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 <<EOF
|
||||
[Match]
|
||||
Name=*
|
||||
|
||||
[Network]
|
||||
DHCP=yes
|
||||
EOF
|
||||
|
||||
# Set up users and groups
|
||||
sudo chroot "${ROOTFS_DIR}" systemd-sysusers --create
|
||||
|
||||
# Configure tmpfiles
|
||||
sudo chroot "${ROOTFS_DIR}" systemd-tmpfiles --create
|
||||
|
||||
# Create essential directories
|
||||
sudo mkdir -p "${ROOTFS_DIR}/usr/lib/systemd/system"
|
||||
sudo mkdir -p "${ROOTFS_DIR}/usr/lib/systemd/user"
|
||||
sudo mkdir -p "${ROOTFS_DIR}/etc/systemd/system"
|
||||
sudo mkdir -p "${ROOTFS_DIR}/etc/systemd/user"
|
||||
sudo mkdir -p "${ROOTFS_DIR}/var/lib/systemd"
|
||||
sudo mkdir -p "${ROOTFS_DIR}/run/systemd"
|
||||
|
||||
# Configure systemd as init
|
||||
sudo ln -sf /lib/systemd/systemd "${ROOTFS_DIR}/sbin/init"
|
||||
|
||||
# Set proper permissions
|
||||
sudo chown -R root:root "${ROOTFS_DIR}"
|
||||
sudo chmod 755 "${ROOTFS_DIR}"
|
||||
|
||||
echo "✅ Rootfs configuration complete!"
|
||||
echo "Rootfs: ${ROOTFS_DIR}/"
|
||||
```
|
||||
|
||||
### Step 2: Create Containerfile for Scratch Build
|
||||
|
||||
Create a `Containerfile.scratch`:
|
||||
|
||||
```dockerfile
|
||||
# Containerfile.scratch - Build bootc image from scratch rootfs
|
||||
FROM scratch
|
||||
|
||||
# Copy the entire rootfs
|
||||
COPY rootfs/ /
|
||||
|
||||
# Install bootc (copy from existing image)
|
||||
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 3: Build Script
|
||||
|
||||
Create the main build script:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build-scratch-bootc.sh - Complete build script for debian-scratch-bootc
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Configuration
|
||||
IMAGE_NAME="debian-scratch-bootc"
|
||||
TAG="${1:-latest}"
|
||||
ROOTFS_DIR="rootfs"
|
||||
|
||||
echo "🏗️ Building Debian Scratch Bootc Base Image"
|
||||
echo "Image: ${IMAGE_NAME}:${TAG}"
|
||||
echo "Rootfs: ${ROOTFS_DIR}/"
|
||||
|
||||
# Check if rootfs exists, build if not
|
||||
if [ ! -d "${ROOTFS_DIR}" ]; then
|
||||
echo "📦 Building rootfs..."
|
||||
./build-rootfs.sh
|
||||
fi
|
||||
|
||||
# Build the base image
|
||||
echo "📦 Building container image..."
|
||||
podman build -f Containerfile.scratch -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 4: Create Example Application Layer
|
||||
|
||||
Create an example showing how to build on top of the base image:
|
||||
|
||||
```dockerfile
|
||||
# examples/nginx/Containerfile
|
||||
FROM debian-scratch-bootc:latest
|
||||
|
||||
# Install nginx
|
||||
RUN apt update && apt install -y nginx && apt clean
|
||||
|
||||
# Configure nginx
|
||||
RUN echo "server { listen 80; location / { return 200 'Hello from bootc!'; } }" > /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 <<EOF
|
||||
[Unit]
|
||||
Description=My Application
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/bin/myapp
|
||||
Restart=always
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
sudo chroot rootfs systemctl enable myapp.service
|
||||
```
|
||||
|
||||
### Security Hardening
|
||||
```bash
|
||||
# Install security packages
|
||||
sudo chroot rootfs apt install -y \
|
||||
apparmor \
|
||||
auditd \
|
||||
ufw \
|
||||
fail2ban
|
||||
|
||||
# Configure AppArmor
|
||||
sudo chroot rootfs systemctl enable apparmor.service
|
||||
```
|
||||
|
||||
This comprehensive guide provides everything needed to create base bootc images using both methods, with practical examples and troubleshooting tips.
|
||||
119
building/bootc-runtime.md
Normal file
119
building/bootc-runtime.md
Normal file
|
|
@ -0,0 +1,119 @@
|
|||
# Container runtime vs "bootc runtime"
|
||||
|
||||
Fundamentally, `bootc` reuses the OCI image format as a way to transport serialized filesystem trees with included metadata such as a `version` label, etc.
|
||||
|
||||
A bootc container operates in two basic modes. First, when invoked by a container runtime such as `podman` or `docker` (typically as part of a build process), the bootc container behaves exactly the same as any other container. For example, although there is a kernel embedded in the container image, it is not executed - the host kernel is used. There's no additional mount namespaces, etc. Ultimately, the container runtime is in full control here.
|
||||
|
||||
The second, and most important mode of operation is when a bootc container is installed to a physical or virtual machine. Here, bootc is in control; the container runtime used to build is no longer relevant. However, it's _very_ important to understand that bootc's role is quite limited:
|
||||
|
||||
* On boot, there is code in the initramfs to do a "chroot" equivalent into the target filesystem root
|
||||
* On upgrade, bootc will fetch new content, but this will not affect the running root
|
||||
|
||||
Crucially, besides setting up some mounts, bootc itself does not act as any kind of "container runtime". It does not set up pid or other namespace, does not change cgroups, etc. That remains the role of other code (typically systemd). `bootc` is not a persistent daemon by default; it does not impose any runtime overhead.
|
||||
|
||||
Another example of this: While one can add Container configuration metadata, `bootc` generally ignores that at runtime today.
|
||||
|
||||
## Labels
|
||||
|
||||
A key aspect of OCI is the ability to use standardized (or semi-standardized) labels. These are stored and rendered by `bootc`; especially the `org.opencontainers.image.version` label.
|
||||
|
||||
## Example ignored runtime metadata, and recommendations
|
||||
|
||||
### ENTRYPOINT and CMD (OCI: Entrypoint/Cmd)
|
||||
|
||||
Ignored by bootc.
|
||||
|
||||
It's recommended for bootc containers to set `CMD /sbin/init`; but this is not required.
|
||||
|
||||
The booted host system will launch from the bootloader, to the kernel+initramfs and real root however it is "physically" configured inside the image. Typically today this is using systemd in both the initramfs and at runtime; but this is up to how you build the image.
|
||||
|
||||
### ENV (OCI: Env)
|
||||
|
||||
Ignored by bootc; to configure the global system environment you can change the systemd configuration. (Though this is generally not a good idea; instead it's usually better to change the environment of individual services)
|
||||
|
||||
### EXPOSE (OCI: exposedPorts)
|
||||
|
||||
Ignored by bootc; it is agnostic to how the system firewall and network function at runtime.
|
||||
|
||||
### USER (OCI: User)
|
||||
|
||||
Ignored by bootc; typically you should configure individual services inside the bootc container to run as unprivileged users instead.
|
||||
|
||||
### HEALTHCHECK (OCI: _no equivalent_)
|
||||
|
||||
This is currently a Docker-specific metadata, and did not make it into the OCI standards. (Note podman healthchecks)
|
||||
|
||||
It is important to understand again is that there is no "outer container runtime" when a bootc container is deployed on a host. The system must perform health checking on itself (or have an external system do it).
|
||||
|
||||
Relevant links:
|
||||
|
||||
* bootc rollback
|
||||
* CentOS Automotive SIG unattended updates (note that as of right now, greenboot does not yet integrate with bootc)
|
||||
* [systemd automatic boot assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT/)
|
||||
|
||||
## Kernel
|
||||
|
||||
When run as a container, the Linux kernel binary in `/usr/lib/modules/$kver/vmlinuz` is ignored. It is only used when a bootc container is deployed to a physical or virtual machine.
|
||||
|
||||
## Security properties
|
||||
|
||||
When run as a container, the container runtime will by default apply various Linux kernel features such as namespacing to isolate the container processes from other system processes.
|
||||
|
||||
None of these isolation properties apply when a bootc system is deployed.
|
||||
|
||||
## Debian-Specific Considerations
|
||||
|
||||
### SELinux
|
||||
|
||||
For more on the intersection of SELinux and current bootc (OSTree container) images, see bootc images - SELinux. Note that Debian does not enable SELinux by default, so this may be less relevant for Debian-based bootc images.
|
||||
|
||||
### AppArmor Integration
|
||||
|
||||
Debian uses AppArmor as its primary mandatory access control system. When building Debian bootc images:
|
||||
|
||||
- AppArmor profiles should be included in the base image
|
||||
- Consider how AppArmor policies will be managed across updates
|
||||
- Test that services work correctly with AppArmor enforcement
|
||||
|
||||
### Debian Security Features
|
||||
|
||||
Debian bootc images should leverage Debian's security features:
|
||||
|
||||
- **Hardened kernel**: Consider using Debian's hardened kernel packages
|
||||
- **Security updates**: Plan for how security updates will be handled through the bootc model
|
||||
- **Package signing**: Ensure proper GPG key management for package verification
|
||||
- **Firewall configuration**: Use `ufw` or `iptables` for network security
|
||||
|
||||
### Example Debian Dockerfile with Security Considerations
|
||||
|
||||
```dockerfile
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
# Install security tools and bootc dependencies
|
||||
RUN apt update && \
|
||||
apt install -y bootc ostree podman apparmor-utils ufw && \
|
||||
apt clean && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Configure AppArmor
|
||||
RUN aa-complain /usr/sbin/sshd
|
||||
|
||||
# Set up basic firewall rules
|
||||
RUN ufw --force enable && \
|
||||
ufw default deny incoming && \
|
||||
ufw default allow outgoing
|
||||
|
||||
# Install your application packages
|
||||
RUN apt update && \
|
||||
apt install -y nginx postgresql && \
|
||||
apt clean && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Configure services with proper security settings
|
||||
RUN systemctl enable nginx postgresql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.
|
||||
|
||||
206
building/guidance.md
Normal file
206
building/guidance.md
Normal file
|
|
@ -0,0 +1,206 @@
|
|||
# Generic guidance for building Debian bootc images
|
||||
|
||||
The bootc project intends to be operating system and distribution independent as possible, similar to its related projects podman and systemd, etc.
|
||||
|
||||
The recommendations for creating bootc-compatible images for Debian will in general need to be owned by the Debian project - in particular those who create the default bootc base image(s). However, some guidance is very generic to most Linux systems (and bootc only supports Linux).
|
||||
|
||||
Let's however restate a base goal of this project:
|
||||
|
||||
> 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.
|
||||
101
building/kernel-arguments.md
Normal file
101
building/kernel-arguments.md
Normal file
|
|
@ -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.
|
||||
|
||||
254
building/management-services.md
Normal file
254
building/management-services.md
Normal file
|
|
@ -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.
|
||||
|
||||
197
building/secrets.md
Normal file
197
building/secrets.md
Normal file
|
|
@ -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: <base64-encoded-password>
|
||||
api-key: <base64-encoded-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.
|
||||
|
||||
222
building/users-and-groups.md
Normal file
222
building/users-and-groups.md
Normal file
|
|
@ -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 <server package>` 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 - <base64 encoded data>
|
||||
```
|
||||
|
||||
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 <<EORUN
|
||||
set -xeuo pipefail
|
||||
groupadd -g 10044 mycustom-group
|
||||
useradd -u 10044 -g 10044 -d /dev/null -M mycustom-user
|
||||
apt install -y mycustom-package.deb
|
||||
bootc container lint
|
||||
EORUN
|
||||
```
|
||||
|
||||
Ultimately the `/etc/passwd` and similar files are a mapping between names and numeric identifiers. A problem then becomes when this mapping is dynamic and mixed with "stateless" container image builds.
|
||||
|
||||
For example today the Debian `postgresql` package allocates a static uid of 26.
|
||||
|
||||
This means that
|
||||
|
||||
```dockerfile
|
||||
RUN apt install -y postgresql
|
||||
```
|
||||
|
||||
will always result in a change to `/etc/passwd` that allocates uid 26 and data in `/var/lib/postgres` will always be owned by that UID.
|
||||
|
||||
However in contrast, some Debian packages allocate floating users.
|
||||
|
||||
This means that each container image build (without additional work, unlike the example at the beginning of this section), may (due to package installation ordering or other reasons) result in the uid changing.
|
||||
|
||||
This can be a problem if that user maintains persistent state. Such cases are best handled by being converted to use `sysusers.d` - or again even better, using `DynamicUser=yes` (see above).
|
||||
|
||||
#### tmpfiles.d use for setting ownership
|
||||
|
||||
Systemd's tmpfiles.d provides a way to define files and directories in a way that will be processed at startup as needed. One way to work around SELinux security context and user or group ownership of a directory or file can be by using the z or Z directives.
|
||||
|
||||
These directives will adjust the access mode, user and group ownership and the SELinux security context as stated on the doc linked above.
|
||||
|
||||
For example, if we need `/var/lib/my_file.conf` to be part of the `tss` group but owned by `root` we could create a tmpfiles.d entry with:
|
||||
|
||||
```
|
||||
+z /var/lib/my_file 0640 root tss -
|
||||
```
|
||||
|
||||
## Debian-Specific Considerations
|
||||
|
||||
### Debian User Management
|
||||
|
||||
When building Debian bootc images, consider these Debian-specific patterns:
|
||||
|
||||
- **adduser vs useradd**: Debian provides both `adduser` (Debian-specific) and `useradd` (POSIX). Use `adduser` for interactive user creation and `useradd` for scripts
|
||||
- **Debian package user creation**: Many Debian packages create users via `adduser` in postinst scripts
|
||||
- **Home directory structure**: Debian uses `/home` for user home directories by default
|
||||
|
||||
### Example Debian User Management
|
||||
|
||||
```dockerfile
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
# Install systemd and bootc dependencies
|
||||
RUN apt update && \
|
||||
apt install -y systemd bootc ostree podman && \
|
||||
apt clean && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Create system users using adduser (Debian way)
|
||||
RUN adduser --system --group --disabled-password --home /var/lib/myservice myservice
|
||||
|
||||
# Or use systemd-sysusers for better integration
|
||||
COPY myservice-user.conf /usr/lib/sysusers.d/
|
||||
|
||||
# Install packages that may create users
|
||||
RUN apt update && \
|
||||
apt install -y postgresql nginx && \
|
||||
apt clean && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Configure services
|
||||
RUN systemctl enable postgresql nginx
|
||||
```
|
||||
|
||||
### Debian SSH Configuration
|
||||
|
||||
For SSH key management in Debian bootc images:
|
||||
|
||||
```dockerfile
|
||||
# Create SSH directory structure
|
||||
RUN mkdir -p /etc/ssh/sshd_config.d
|
||||
|
||||
# Add SSH configuration
|
||||
COPY sshd_config.d/99-bootc.conf /etc/ssh/sshd_config.d/
|
||||
|
||||
# Set up authorized keys via tmpfiles
|
||||
COPY ssh-keys.conf /usr/lib/tmpfiles.d/
|
||||
```
|
||||
|
||||
### Debian Group Management
|
||||
|
||||
Debian uses specific group conventions:
|
||||
|
||||
- **sudo group**: `sudo` (not `wheel` like some other distributions)
|
||||
- **docker group**: For Docker access
|
||||
- **systemd groups**: For systemd-resolved, systemd-timesyncd, etc.
|
||||
|
||||
---
|
||||
|
||||
The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.
|
||||
|
||||
|
|
@ -0,0 +1,691 @@
|
|||
# bootc composefs-finalize-staged - Examples and Troubleshooting
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides practical examples and troubleshooting guidance for the `bootc composefs-finalize-staged` system, covering common use cases, error scenarios, and debugging techniques.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Systemd Service Management
|
||||
|
||||
#### Enable and Start Service
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Enable and start composefs-finalize-staged service
|
||||
|
||||
echo "=== Composefs Finalize Staged Service Management ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Enable service for automatic start
|
||||
echo "Enabling service..."
|
||||
systemctl enable composefs-finalize-staged.service
|
||||
|
||||
# Start service
|
||||
echo "Starting service..."
|
||||
systemctl start composefs-finalize-staged.service
|
||||
|
||||
# Check service status
|
||||
echo "Service status:"
|
||||
systemctl status composefs-finalize-staged.service
|
||||
```
|
||||
|
||||
#### Service Monitoring
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Monitor composefs-finalize-staged service
|
||||
|
||||
echo "=== Service Monitoring ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check service status
|
||||
echo "Service status:"
|
||||
systemctl is-active composefs-finalize-staged.service
|
||||
|
||||
# Check service logs
|
||||
echo "Recent logs:"
|
||||
journalctl -u composefs-finalize-staged.service -n 50
|
||||
|
||||
# Check service configuration
|
||||
echo "Service configuration:"
|
||||
systemctl show composefs-finalize-staged.service
|
||||
```
|
||||
|
||||
### 2. Staged Deployment Management
|
||||
|
||||
#### Check Staged Deployment
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Check for staged composefs deployment
|
||||
|
||||
echo "=== Staged Deployment Check ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check if staged deployment exists
|
||||
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 directory
|
||||
echo "Composefs state directory:"
|
||||
ls -la /sysroot/composefs/
|
||||
|
||||
# Check staged deployment files
|
||||
echo "Staged deployment files:"
|
||||
find /sysroot/composefs/ -name "*.staged" -type f
|
||||
```
|
||||
|
||||
#### Create Staged Deployment
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Create staged composefs deployment
|
||||
|
||||
echo "=== Create Staged Deployment ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Create composefs state directory
|
||||
mkdir -p /sysroot/composefs
|
||||
|
||||
# Create staged deployment marker
|
||||
echo "staged-deployment-id" > /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.
|
||||
|
|
@ -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 <subcommand> [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...] <device> <directory>`
|
||||
**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...] <directory>`
|
||||
**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...] <file>`
|
||||
**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...] <image> <directory>`
|
||||
**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...] <image> <mountpoint>`
|
||||
**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...] <device>`
|
||||
**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...] <source> <destination>`
|
||||
**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...] <source> <destination>`
|
||||
**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...] <file>`
|
||||
**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...] <target> <link>`
|
||||
**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...] <directory>`
|
||||
**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...] <directory>`
|
||||
**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...] <pid>`
|
||||
**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...] <url>`
|
||||
**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...] <url>`
|
||||
**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...] <archive> [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 <command> [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 <subcommand> [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 <subcommand> [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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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<Host> {
|
||||
// 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.
|
||||
419
composefs.md
Normal file
419
composefs.md
Normal file
|
|
@ -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<str>,
|
||||
}
|
||||
|
||||
// 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<String>,
|
||||
) -> 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.
|
||||
883
edit/bootc-edit-external-commands.md
Normal file
883
edit/bootc-edit-external-commands.md
Normal file
|
|
@ -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.
|
||||
321
edit/bootc-edit-flowchart.md
Normal file
321
edit/bootc-edit-flowchart.md
Normal file
|
|
@ -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.
|
||||
476
edit/bootc-edit-technical-guide.md
Normal file
476
edit/bootc-edit-technical-guide.md
Normal file
|
|
@ -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<ImageReference>, // 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<String>, // 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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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...] <file> [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...] <device> <directory>`
|
||||
**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...] <directory>`
|
||||
**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...] <directory> <command>`
|
||||
**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 <directory>`
|
||||
**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...] <pid>`
|
||||
**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...] <url>`
|
||||
**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...] <url>`
|
||||
**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 <subcommand> [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 <subcommand> [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 <subcommand> [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...] <device>`
|
||||
**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...] <archive> [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 <command> [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 <subcommand> [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 <subcommand> [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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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 <command>
|
||||
```
|
||||
|
||||
2. **Check namespace availability**
|
||||
```bash
|
||||
ls -la /proc/1/ns/mnt
|
||||
```
|
||||
|
||||
3. **Check privileges**
|
||||
```bash
|
||||
whoami
|
||||
sudo bootc exec-in-host-mount-namespace <command>
|
||||
```
|
||||
|
||||
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.
|
||||
|
|
@ -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<OsString>,
|
||||
}
|
||||
```
|
||||
|
||||
## 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<Command> {
|
||||
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<Command> {
|
||||
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.
|
||||
1312
image/bootc-image-external-commands.md
Normal file
1312
image/bootc-image-external-commands.md
Normal file
File diff suppressed because it is too large
Load diff
456
image/bootc-image-flowchart.md
Normal file
456
image/bootc-image-flowchart.md
Normal file
|
|
@ -0,0 +1,456 @@
|
|||
# bootc image - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc image` process flow, showing the decision points, operations, and data structures involved in managing container images in the bootc storage system.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc image │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Command Arguments │
|
||||
│ │
|
||||
│ • Parse subcommand (list, copy-to-storage, etc.) │
|
||||
│ • Parse command-specific options │
|
||||
│ • Validate arguments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Route to Subcommand │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Subcommand Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ List │ │ Copy-to-Storage│ │ Pull-from-Default│ │
|
||||
│ │ │ │ │ │ Storage │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ List Images ││ │ │ Copy Image ││ │ │ Pull Image ││ │
|
||||
│ │ │ • Host ││ │ │ • Source ││ │ │ • From Host ││ │
|
||||
│ │ │ • Logical ││ │ │ • Target ││ │ │ • To Bootc ││ │
|
||||
│ │ │ • All ││ │ │ • Export ││ │ │ • Import ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Cmd Wrapper │ │
|
||||
│ │ │ │
|
||||
│ │ • List: podman image list │ │
|
||||
│ │ • Build: podman image build │ │
|
||||
│ │ • Pull: podman image pull │ │
|
||||
│ │ • Push: podman image push │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Image operation completed successfully │
|
||||
│ • Results displayed or returned │
|
||||
│ • Storage updated if applicable │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Image Listing Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Image Listing Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine List Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ List Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ All │ │ Logical │ │ Host │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ List Both ││ │ │ List Only ││ │ │ List Only ││ │
|
||||
│ │ │ • Host ││ │ │ Logical ││ │ │ Host ││ │
|
||||
│ │ │ • Logical ││ │ │ Images ││ │ │ Images ││ │
|
||||
│ │ │ Images ││ │ │ • Bound ││ │ │ • OSTree ││ │
|
||||
│ │ │ Combined ││ │ │ Images ││ │ │ Repo ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check System Status │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ System Booted? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Get Storage ││ │ │ Use Root Filesystem ││ │
|
||||
│ │ │ • OSTree ││ │ │ ││ │
|
||||
│ │ │ Repo ││ │ │ • Query Bound Images ││ │
|
||||
│ │ │ • Images ││ │ │ • List Logical Images ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Query Images │
|
||||
│ │
|
||||
│ • Query OSTree repository for host images │
|
||||
│ • Query bound images for logical images │
|
||||
│ • Combine results based on list type │
|
||||
│ • Format results according to output format │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Format Output │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Output Format? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Table │ │ JSON │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Format as ││ │ │ Format as JSON ││ │
|
||||
│ │ │ Table ││ │ │ ││ │
|
||||
│ │ │ • Headers ││ │ │ • Pretty Print ││ │
|
||||
│ │ │ • Rows ││ │ │ • Structured Data ││ │
|
||||
│ │ │ • Columns ││ │ │ • Machine Readable ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Image Copying Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Image Copying Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Source and Target │
|
||||
│ │
|
||||
│ • Source: Use provided source or current booted image │
|
||||
│ • Target: Use provided target or default (localhost/bootc) │
|
||||
│ • Validate source and target formats │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Source Image │
|
||||
│ │
|
||||
│ • Check if source image exists in bootc storage │
|
||||
│ • Verify image integrity │
|
||||
│ • Get image metadata │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Target Storage │
|
||||
│ │
|
||||
│ • Verify target storage is available │
|
||||
│ • Check if target already exists │
|
||||
│ • Prepare target storage if needed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Copy Image │
|
||||
│ │
|
||||
│ • Use podman to copy image │
|
||||
│ • Tag image with target name │
|
||||
│ • Verify copy operation success │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Copy │
|
||||
│ │
|
||||
│ • Check if target image exists │
|
||||
│ • Verify image integrity │
|
||||
│ • Update metadata │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Image successfully copied │
|
||||
│ • Target image available in containers-storage │
|
||||
│ • Image ready for use with podman │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Image Pulling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Image Pulling Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Validate Source Image │
|
||||
│ │
|
||||
│ • Check if source image exists in default storage │
|
||||
│ • Verify image format and integrity │
|
||||
│ • Get image metadata │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Prepare Bootc Storage │
|
||||
│ │
|
||||
│ • Ensure bootc storage is initialized │
|
||||
│ • Create storage directories if needed │
|
||||
│ • Set up storage configuration │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Copy from Host Storage │
|
||||
│ │
|
||||
│ • Use podman to copy from default storage │
|
||||
│ • Set up storage roots and bindings │
|
||||
│ • Copy image to bootc storage │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Import │
|
||||
│ │
|
||||
│ • Check if image exists in bootc storage │
|
||||
│ │ • Verify image integrity │
|
||||
│ │ • Update metadata │
|
||||
│ │ • Register with OSTree if needed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Image successfully imported │
|
||||
│ • Image available in bootc storage │
|
||||
│ • Image ready for deployment │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Podman Command Wrapper Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Podman Command Wrapper │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Command │
|
||||
│ │
|
||||
│ • Determine podman subcommand (list, build, pull, push) │
|
||||
│ • Parse command arguments │
|
||||
│ • Validate command syntax │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Prepare Podman Command │
|
||||
│ │
|
||||
│ • Create podman command instance │
|
||||
│ • Set up storage roots and bindings │
|
||||
│ • Configure command arguments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Command │
|
||||
│ │
|
||||
│ • Run podman command with bootc storage │
|
||||
│ • Capture output and error streams │
|
||||
│ • Monitor command execution │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Handle Results │
|
||||
│ │
|
||||
│ • Check command exit status │
|
||||
│ • Process output if needed │
|
||||
│ • Handle errors appropriately │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Return Results │
|
||||
│ │
|
||||
│ • Return success or failure status │
|
||||
│ • Pass through output to user │
|
||||
│ • Update storage metadata if needed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Storage Management Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Storage Management │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Storage Status │
|
||||
│ │
|
||||
│ • Verify bootc storage is initialized │
|
||||
│ • Check storage configuration │
|
||||
│ • Validate storage permissions │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize Storage if Needed │
|
||||
│ │
|
||||
│ • Create storage directories │
|
||||
│ • Set up storage configuration │
|
||||
│ • Initialize storage metadata │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Perform Storage Operations │
|
||||
│ │
|
||||
│ • List images in storage │
|
||||
│ • Check image existence │
|
||||
│ • Pull/push images as needed │
|
||||
│ • Update storage metadata │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Cleanup and Maintenance │
|
||||
│ │
|
||||
│ • Clean up temporary files │
|
||||
│ • Update storage statistics │
|
||||
│ • Perform garbage collection if needed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Image │ │ Storage │ │ Podman │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Image not │ │ • Storage not │ │ • Command │ │
|
||||
│ │ found │ │ available │ │ failed │ │
|
||||
│ │ • Invalid │ │ • Permission │ │ • Invalid │ │
|
||||
│ │ format │ │ denied │ │ arguments │ │
|
||||
│ │ • Corrupted │ │ • Full storage │ │ • Network │ │
|
||||
│ │ image │ │ • Configuration │ │ error │ │
|
||||
│ │ │ │ error │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up any partial state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Storage States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initial State │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Uninitialized Storage │ │
|
||||
│ │ │ │
|
||||
│ │ • No storage directories │ │
|
||||
│ │ • No configuration │ │
|
||||
│ │ • No images available │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Initialize Storage │ │
|
||||
│ │ │ │
|
||||
│ │ • Create storage directories │ │
|
||||
│ │ • Set up configuration │ │
|
||||
│ │ • Initialize metadata │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Initialized Storage │ │
|
||||
│ │ │ │
|
||||
│ │ • Storage directories exist │ │
|
||||
│ │ • Configuration available │ │
|
||||
│ │ • Ready for operations │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Image Operations │ │
|
||||
│ │ │ │
|
||||
│ │ • List images │ │
|
||||
│ │ • Copy images │ │
|
||||
│ │ • Pull images │ │
|
||||
│ │ • Manage storage │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Active Storage with Images │ │
|
||||
│ │ │ │
|
||||
│ │ • Images stored and available │ │
|
||||
│ │ • Operations working │ │
|
||||
│ │ • Metadata up to date │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc image process, showing all decision points, operations, and state transitions involved in managing container images in the bootc storage system.
|
||||
616
image/bootc-image-technical-guide.md
Normal file
616
image/bootc-image-technical-guide.md
Normal file
|
|
@ -0,0 +1,616 @@
|
|||
# bootc image - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc image` is a command for managing container images in the bootc storage system. It provides operations for listing, copying, and managing container images that are distinct from the standard `podman` image storage. The command operates on bootc's own container storage and provides integration with the broader container ecosystem.
|
||||
|
||||
## Purpose
|
||||
|
||||
The image command serves several critical functions:
|
||||
|
||||
1. **Image Listing**: List images stored in bootc storage
|
||||
2. **Image Copying**: Copy images between storage systems
|
||||
3. **Storage Management**: Manage bootc's container storage
|
||||
4. **Podman Integration**: Provide wrapper commands for podman operations
|
||||
5. **Image Discovery**: Discover and manage host and logical images
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc image <COMMAND> [OPTIONS...]
|
||||
```
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | Description | Purpose |
|
||||
|---------|-------------|---------|
|
||||
| `list` | List fetched images stored in bootc storage | Display available images |
|
||||
| `copy-to-storage` | Copy image from bootc storage to containers-storage | Export images |
|
||||
| `pull-from-default-storage` | Copy image from default containers-storage to bootc storage | Import images |
|
||||
| `cmd` | Wrapper for selected podman image subcommands | Podman integration |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 1. Image Command Structure
|
||||
|
||||
```rust
|
||||
pub(crate) enum ImageOpts {
|
||||
List {
|
||||
list_type: ImageListType,
|
||||
list_format: ImageListFormat,
|
||||
},
|
||||
CopyToStorage {
|
||||
source: Option<String>,
|
||||
target: Option<String>,
|
||||
},
|
||||
PullFromDefaultStorage {
|
||||
image: String,
|
||||
},
|
||||
Cmd(ImageCmdOpts),
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Image List Types
|
||||
|
||||
```rust
|
||||
pub(crate) enum ImageListType {
|
||||
All, // List all images
|
||||
Logical, // List only logically bound images
|
||||
Host, // List only host images
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Image List Formats
|
||||
|
||||
```rust
|
||||
pub(crate) enum ImageListFormat {
|
||||
Table, // Human readable table format
|
||||
Json, // JSON format
|
||||
}
|
||||
```
|
||||
|
||||
## Image Listing
|
||||
|
||||
### 1. List Command
|
||||
|
||||
```bash
|
||||
# List all images
|
||||
bootc image list
|
||||
|
||||
# List with specific type
|
||||
bootc image list --type=host
|
||||
|
||||
# List in JSON format
|
||||
bootc image list --format=json
|
||||
```
|
||||
|
||||
### 2. Image Types
|
||||
|
||||
#### Host Images
|
||||
- **Source**: Images stored in OSTree repository
|
||||
- **Location**: `/sysroot/ostree/repo`
|
||||
- **Purpose**: Images used by bootc deployments
|
||||
- **Management**: Managed by bootc upgrade/switch
|
||||
|
||||
#### Logical Images
|
||||
- **Source**: Images referenced by deployments
|
||||
- **Location**: Bound image references
|
||||
- **Purpose**: Images that can be deployed
|
||||
- **Management**: Referenced but not necessarily stored locally
|
||||
|
||||
### 3. List Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) async fn list_images(list_type: ImageListType) -> Result<Vec<ImageOutput>> {
|
||||
let rootfs = cap_std::fs::Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
|
||||
let sysroot = if ostree_booted()? {
|
||||
Some(crate::cli::get_storage().await?)
|
||||
} else {
|
||||
None
|
||||
};
|
||||
|
||||
Ok(match (list_type, sysroot) {
|
||||
(ImageListType::All, None) => list_logical_images(&rootfs)?,
|
||||
(ImageListType::All, Some(sysroot)) => list_host_images(&sysroot)?
|
||||
.into_iter()
|
||||
.chain(list_logical_images(&rootfs)?)
|
||||
.collect(),
|
||||
(ImageListType::Logical, _) => list_logical_images(&rootfs)?,
|
||||
(ImageListType::Host, None) => {
|
||||
bail!("Listing host images requires a booted bootc system")
|
||||
}
|
||||
(ImageListType::Host, Some(sysroot)) => list_host_images(&sysroot)?,
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## Image Copying
|
||||
|
||||
### 1. Copy to Storage
|
||||
|
||||
```bash
|
||||
# Copy current booted image to containers-storage
|
||||
bootc image copy-to-storage
|
||||
|
||||
# Copy specific image to containers-storage
|
||||
bootc image copy-to-storage --source=quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Copy to specific target
|
||||
bootc image copy-to-storage --target=localhost/myimage:latest
|
||||
```
|
||||
|
||||
**Purpose**: Export images from bootc storage to standard container storage
|
||||
**Use Cases**:
|
||||
- Making images available to podman
|
||||
- Sharing images with other tools
|
||||
- Backup and migration
|
||||
|
||||
### 2. Pull from Default Storage
|
||||
|
||||
```bash
|
||||
# Pull image from default containers-storage
|
||||
bootc image pull-from-default-storage quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
**Purpose**: Import images from standard container storage to bootc storage
|
||||
**Use Cases**:
|
||||
- Importing images built with podman
|
||||
- Migrating images from other systems
|
||||
- Testing with locally built images
|
||||
|
||||
### 3. Copy Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) async fn push_entrypoint(
|
||||
source: Option<&str>,
|
||||
target: Option<&str>,
|
||||
) -> Result<()> {
|
||||
let sysroot = get_storage().await?;
|
||||
let imgstore = sysroot.get_ensure_imgstore()?;
|
||||
|
||||
let source = source.unwrap_or_else(|| {
|
||||
// Get current booted image
|
||||
get_current_booted_image(&sysroot)
|
||||
});
|
||||
|
||||
let target = target.unwrap_or(IMAGE_DEFAULT);
|
||||
|
||||
// Copy image from bootc storage to containers-storage
|
||||
imgstore.copy_to_containers_storage(&source, &target).await?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Podman Integration
|
||||
|
||||
### 1. Command Wrapper
|
||||
|
||||
```bash
|
||||
# List images using podman
|
||||
bootc image cmd list
|
||||
|
||||
# Build image using podman
|
||||
bootc image cmd build -t myimage:latest .
|
||||
|
||||
# Pull image using podman
|
||||
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Push image using podman
|
||||
bootc image cmd push myimage:latest
|
||||
```
|
||||
|
||||
### 2. Supported Commands
|
||||
|
||||
| Command | Description | Podman Equivalent |
|
||||
|---------|-------------|-------------------|
|
||||
| `list` | List images | `podman image list` |
|
||||
| `build` | Build image | `podman image build` |
|
||||
| `pull` | Pull image | `podman image pull` |
|
||||
| `push` | Push image | `podman image push` |
|
||||
|
||||
### 3. Command Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) async fn imgcmd_entrypoint(
|
||||
imgstore: &CStorage,
|
||||
cmd: &str,
|
||||
args: &[OsString],
|
||||
) -> Result<()> {
|
||||
let mut cmd = imgstore.new_image_cmd()?;
|
||||
cmd.arg(cmd);
|
||||
cmd.args(args);
|
||||
|
||||
let status = cmd.status()?;
|
||||
if !status.success() {
|
||||
std::process::exit(status.code().unwrap_or(1));
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Storage Management
|
||||
|
||||
### 1. Bootc Storage
|
||||
|
||||
**Location**: `/var/lib/bootc/containers/`
|
||||
**Purpose**: Bootc's dedicated container storage
|
||||
**Features**:
|
||||
- Isolated from system podman storage
|
||||
- Optimized for bootc operations
|
||||
- Integrated with OSTree
|
||||
|
||||
### 2. Storage Operations
|
||||
|
||||
#### List Images
|
||||
```rust
|
||||
pub(crate) async fn list_images(&self) -> Result<Vec<ImageListEntry>> {
|
||||
let mut cmd = self.new_image_cmd()?;
|
||||
cmd.args(["list", "--format=json"]);
|
||||
cmd.stdin(Stdio::null());
|
||||
|
||||
let mut stdout = tempfile::tempfile()?;
|
||||
cmd.stdout(stdout.try_clone()?);
|
||||
|
||||
let status = cmd.status()?;
|
||||
if !status.success() {
|
||||
// Handle error
|
||||
}
|
||||
|
||||
// Parse JSON output
|
||||
stdout.rewind()?;
|
||||
let images: Vec<ImageListEntry> = serde_json::from_reader(stdout)?;
|
||||
Ok(images)
|
||||
}
|
||||
```
|
||||
|
||||
#### Check Image Exists
|
||||
```rust
|
||||
pub(crate) async fn exists(&self, image: &str) -> Result<bool> {
|
||||
let mut cmd = AsyncCommand::from(self.new_image_cmd()?);
|
||||
cmd.args(["exists", image]);
|
||||
Ok(cmd.status().await?.success())
|
||||
}
|
||||
```
|
||||
|
||||
#### Pull Image
|
||||
```rust
|
||||
pub(crate) async fn pull(&self, image: &str, mode: PullMode) -> Result<bool> {
|
||||
match mode {
|
||||
PullMode::IfNotExists => {
|
||||
if self.exists(image).await? {
|
||||
return Ok(false);
|
||||
}
|
||||
}
|
||||
PullMode::Always => {}
|
||||
};
|
||||
|
||||
let mut cmd = self.new_image_cmd()?;
|
||||
cmd.args(["pull", image]);
|
||||
|
||||
let status = cmd.status()?;
|
||||
Ok(status.success())
|
||||
}
|
||||
```
|
||||
|
||||
## Image Types and Sources
|
||||
|
||||
### 1. Host Images
|
||||
|
||||
**Definition**: Images stored in the OSTree repository
|
||||
**Location**: `/sysroot/ostree/repo`
|
||||
**Management**: Managed by bootc operations
|
||||
**Use Cases**: Deployed images, system images
|
||||
|
||||
```rust
|
||||
fn list_host_images(sysroot: &crate::store::Storage) -> Result<Vec<ImageOutput>> {
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = ostree.repo();
|
||||
let images = ostree_ext::container::store::list_images(&repo)?;
|
||||
|
||||
Ok(images
|
||||
.into_iter()
|
||||
.map(|img| ImageOutput {
|
||||
image_type: ImageListTypeColumn::Host,
|
||||
image: img,
|
||||
})
|
||||
.collect())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Logical Images
|
||||
|
||||
**Definition**: Images referenced by deployments but not necessarily stored
|
||||
**Location**: Bound image references
|
||||
**Management**: Referenced by deployment configurations
|
||||
**Use Cases**: Available for deployment, referenced images
|
||||
|
||||
```rust
|
||||
fn list_logical_images(rootfs: &Dir) -> Result<Vec<ImageOutput>> {
|
||||
let bound_images = query_bound_images(rootfs)?;
|
||||
|
||||
Ok(bound_images
|
||||
.into_iter()
|
||||
.map(|img| ImageOutput {
|
||||
image_type: ImageListTypeColumn::Logical,
|
||||
image: img.image,
|
||||
})
|
||||
.collect())
|
||||
}
|
||||
```
|
||||
|
||||
## Image Operations
|
||||
|
||||
### 1. Image Copying Process
|
||||
|
||||
```rust
|
||||
pub(crate) async fn copy_to_containers_storage(
|
||||
&self,
|
||||
source: &str,
|
||||
target: &str,
|
||||
) -> Result<()> {
|
||||
// 1. Verify source image exists
|
||||
if !self.exists(source).await? {
|
||||
bail!("Source image not found: {}", source);
|
||||
}
|
||||
|
||||
// 2. Create target storage if needed
|
||||
self.ensure_storage_exists()?;
|
||||
|
||||
// 3. Copy image using podman
|
||||
let mut cmd = self.new_image_cmd()?;
|
||||
cmd.args(["tag", source, target]);
|
||||
|
||||
let status = cmd.status()?;
|
||||
if !status.success() {
|
||||
bail!("Failed to copy image: {}", source);
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Image Pulling Process
|
||||
|
||||
```rust
|
||||
pub(crate) async fn pull_from_host_storage(&self, image: &str) -> Result<()> {
|
||||
let mut cmd = Command::new("podman");
|
||||
cmd.stdin(Stdio::null());
|
||||
cmd.stdout(Stdio::null());
|
||||
|
||||
// Set up storage roots
|
||||
let temp_runroot = TempDir::new(cap_std::ambient_authority())?;
|
||||
bind_storage_roots(&mut cmd, &self.storage_root, &temp_runroot)?;
|
||||
|
||||
// Copy from host storage to bootc storage
|
||||
let storage_dest = &format!(
|
||||
"containers-storage:[overlay@{}+/proc/self/fd/{}]",
|
||||
STORAGE_ALIAS_DIR, STORAGE_RUN_FD
|
||||
);
|
||||
|
||||
cmd.args(["tag", image, storage_dest]);
|
||||
|
||||
let status = cmd.status()?;
|
||||
if !status.success() {
|
||||
bail!("Failed to pull image from host storage: {}", image);
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Common Errors
|
||||
|
||||
#### Image Not Found
|
||||
```bash
|
||||
Error: Source image not found: quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
**Solution**: Verify image exists in bootc storage
|
||||
```bash
|
||||
bootc image list
|
||||
```
|
||||
|
||||
#### Storage Not Available
|
||||
```bash
|
||||
Error: Bootc storage not available
|
||||
```
|
||||
|
||||
**Solution**: Check storage initialization
|
||||
```bash
|
||||
bootc status
|
||||
```
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
Error: Permission denied
|
||||
```
|
||||
|
||||
**Solution**: Run with appropriate privileges
|
||||
```bash
|
||||
sudo bootc image list
|
||||
```
|
||||
|
||||
### 2. Error Recovery
|
||||
|
||||
#### Storage Corruption
|
||||
```bash
|
||||
# Reinitialize storage
|
||||
bootc image cmd prune -a
|
||||
|
||||
# Rebuild storage
|
||||
bootc image cmd build --no-cache
|
||||
```
|
||||
|
||||
#### Image Corruption
|
||||
```bash
|
||||
# Remove corrupted image
|
||||
bootc image cmd rmi corrupted-image
|
||||
|
||||
# Re-pull image
|
||||
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### 1. Development Workflow
|
||||
|
||||
```bash
|
||||
# Build image with podman
|
||||
bootc image cmd build -t myimage:latest .
|
||||
|
||||
# Copy to bootc storage
|
||||
bootc image copy-to-storage --source=myimage:latest
|
||||
|
||||
# Deploy image
|
||||
bootc switch myimage:latest
|
||||
```
|
||||
|
||||
### 2. Production Workflow
|
||||
|
||||
```bash
|
||||
# Pull production image
|
||||
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Copy to bootc storage
|
||||
bootc image copy-to-storage --source=quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Deploy image
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
### 3. Backup and Migration
|
||||
|
||||
```bash
|
||||
# List all images
|
||||
bootc image list --format=json > images.json
|
||||
|
||||
# Copy images to standard storage
|
||||
bootc image copy-to-storage --source=image1
|
||||
bootc image copy-to-storage --source=image2
|
||||
|
||||
# Export with podman
|
||||
podman save -o backup.tar localhost/bootc
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Storage Efficiency
|
||||
|
||||
**Image Deduplication**: Bootc storage uses OSTree for efficient storage
|
||||
**Layer Sharing**: Common layers are shared between images
|
||||
**Compression**: Images are compressed for storage efficiency
|
||||
|
||||
### 2. Operation Performance
|
||||
|
||||
**Parallel Operations**: Multiple operations can run in parallel
|
||||
**Caching**: Frequently accessed images are cached
|
||||
**Lazy Loading**: Images are loaded on demand
|
||||
|
||||
### 3. Storage Management
|
||||
|
||||
**Cleanup**: Regular cleanup of unused images
|
||||
**Garbage Collection**: Automatic garbage collection of unused layers
|
||||
**Space Monitoring**: Monitor storage usage
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Image Verification
|
||||
|
||||
**Signature Verification**: Images are verified using container signatures
|
||||
**Integrity Checks**: Image integrity is verified during operations
|
||||
**Access Control**: Proper access control for storage operations
|
||||
|
||||
### 2. Storage Isolation
|
||||
|
||||
**Separate Storage**: Bootc storage is isolated from system storage
|
||||
**Permission Management**: Proper permissions for storage access
|
||||
**Audit Logging**: Operations are logged for audit purposes
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### Images Not Listed
|
||||
```bash
|
||||
# Check storage status
|
||||
bootc status
|
||||
|
||||
# Verify storage initialization
|
||||
ls -la /var/lib/bootc/containers/
|
||||
```
|
||||
|
||||
#### Copy Operations Fail
|
||||
```bash
|
||||
# Check source image
|
||||
bootc image list
|
||||
|
||||
# Check target storage
|
||||
podman images
|
||||
```
|
||||
|
||||
#### Podman Commands Fail
|
||||
```bash
|
||||
# Check podman installation
|
||||
podman --version
|
||||
|
||||
# Check storage configuration
|
||||
podman info
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc image list
|
||||
|
||||
# Check storage details
|
||||
bootc image cmd list --format=json
|
||||
|
||||
# Verify image integrity
|
||||
bootc image cmd inspect image-name
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Image Management
|
||||
|
||||
- **Regular Cleanup**: Clean up unused images regularly
|
||||
- **Image Tagging**: Use meaningful tags for images
|
||||
- **Version Control**: Keep track of image versions
|
||||
- **Backup Strategy**: Implement backup strategy for important images
|
||||
|
||||
### 2. Storage Management
|
||||
|
||||
- **Monitor Usage**: Monitor storage usage regularly
|
||||
- **Optimize Storage**: Use efficient storage configurations
|
||||
- **Cleanup Policies**: Implement cleanup policies
|
||||
- **Backup Storage**: Backup storage configurations
|
||||
|
||||
### 3. Integration
|
||||
|
||||
- **Automation**: Automate image operations where possible
|
||||
- **Monitoring**: Monitor image operations
|
||||
- **Documentation**: Document image management procedures
|
||||
- **Testing**: Test image operations regularly
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Image Signing**: Enhanced image signing capabilities
|
||||
- **Image Encryption**: Image encryption support
|
||||
- **Advanced Filtering**: More advanced image filtering
|
||||
- **Bulk Operations**: Bulk image operations
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **Registry Integration**: Better registry integration
|
||||
- **CI/CD Integration**: Enhanced CI/CD integration
|
||||
- **Monitoring Integration**: Better monitoring integration
|
||||
- **API Support**: REST API for image operations
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc image system's architecture, implementation, and usage patterns.
|
||||
422
install/external-commands-reference.md
Normal file
422
install/external-commands-reference.md
Normal file
|
|
@ -0,0 +1,422 @@
|
|||
# bootc External Commands Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive reference for all external commands used by bootc during the installation process. These commands are executed by bootc to perform various system operations that cannot be handled internally.
|
||||
|
||||
## Required Commands
|
||||
|
||||
### 1. ostree - OSTree Repository Management
|
||||
|
||||
**Purpose**: Manages OSTree repositories for atomic updates and deployments
|
||||
|
||||
**Package**: `ostree`
|
||||
|
||||
**Key Commands Used**:
|
||||
|
||||
```bash
|
||||
# Initialize OSTree filesystem
|
||||
ostree admin init-fs --modern .
|
||||
|
||||
# Configure repository settings
|
||||
ostree config --repo ostree/repo set sysroot.bootloader none
|
||||
ostree config --repo ostree/repo set sysroot.bootprefix true
|
||||
ostree config --repo ostree/repo set sysroot.readonly true
|
||||
|
||||
# Parse commit information
|
||||
ostree --repo=/ostree/repo rev-parse --single
|
||||
|
||||
# Read commit metadata
|
||||
ostree read-commit <commit-hash>
|
||||
```
|
||||
|
||||
**Configuration Files**:
|
||||
- Repository config: `ostree/repo/config`
|
||||
- Deployment config: `ostree/deploy/*/var/lib/ostree/config`
|
||||
|
||||
**Error Handling**:
|
||||
- Repository corruption detection
|
||||
- Commit validation
|
||||
- Configuration validation
|
||||
|
||||
### 2. bootupd - Bootloader Management
|
||||
|
||||
**Purpose**: Manages bootloader installation and configuration
|
||||
|
||||
**Package**: `bootupd`
|
||||
|
||||
**Key Commands Used**:
|
||||
|
||||
```bash
|
||||
# Install bootloader
|
||||
bootupctl install
|
||||
|
||||
# Generate bootloader configuration
|
||||
bootupctl generate
|
||||
|
||||
# Check bootloader status
|
||||
bootupctl status
|
||||
|
||||
# Update bootloader
|
||||
bootupctl update
|
||||
```
|
||||
|
||||
**Configuration Files**:
|
||||
- Bootloader state: `/boot/bootupd-state.json`
|
||||
- GRUB config: `/boot/grub2/grub.cfg`
|
||||
- EFI config: `/boot/efi/EFI/*/grub.cfg`
|
||||
|
||||
**Architecture Support**:
|
||||
- x86_64: GRUB2
|
||||
- aarch64: GRUB2
|
||||
- s390x: zipl (via separate implementation)
|
||||
|
||||
### 3. podman - Container Runtime
|
||||
|
||||
**Purpose**: Container runtime for running bootc installation
|
||||
|
||||
**Package**: `podman`
|
||||
|
||||
**Required Flags**:
|
||||
```bash
|
||||
podman run --rm --privileged --pid=host \
|
||||
-v /var/lib/containers:/var/lib/containers \
|
||||
-v /dev:/dev \
|
||||
--security-opt label=type:unconfined_t \
|
||||
<image> bootc install to-disk /dev/target
|
||||
```
|
||||
|
||||
**Container Environment Variables**:
|
||||
- `CONTAINER_ENGINE=podman`
|
||||
- `CONTAINER_IMAGE_ID=<image-id>`
|
||||
- `CONTAINER_IMAGE=<image-name>`
|
||||
- `CONTAINER_ROOTLESS=<0|1>`
|
||||
|
||||
### 4. Filesystem Management Commands
|
||||
|
||||
#### fstrim - Filesystem Optimization
|
||||
|
||||
**Purpose**: Trim filesystem to optimize performance
|
||||
|
||||
**Package**: `util-linux`
|
||||
|
||||
**Command Used**:
|
||||
```bash
|
||||
fstrim --quiet-unsupported -v /target
|
||||
```
|
||||
|
||||
**Options**:
|
||||
- `--quiet-unsupported`: Suppress errors for unsupported filesystems
|
||||
- `-v`: Verbose output
|
||||
|
||||
#### mount/umount - Filesystem Mounting
|
||||
|
||||
**Purpose**: Mount and unmount filesystems
|
||||
|
||||
**Package**: `util-linux`
|
||||
|
||||
**Commands Used**:
|
||||
```bash
|
||||
# Mount filesystem
|
||||
mount /dev/target /mnt
|
||||
|
||||
# Remount read-only
|
||||
mount -o remount,ro /target
|
||||
|
||||
# Unmount filesystem
|
||||
umount -R /target
|
||||
```
|
||||
|
||||
#### fsfreeze - Filesystem Freeze/Thaw
|
||||
|
||||
**Purpose**: Freeze and thaw filesystems for consistency
|
||||
|
||||
**Package**: `util-linux`
|
||||
|
||||
**Commands Used**:
|
||||
```bash
|
||||
# Freeze filesystem
|
||||
fsfreeze -f /target
|
||||
|
||||
# Thaw filesystem
|
||||
fsfreeze -u /target
|
||||
```
|
||||
|
||||
## Optional Commands
|
||||
|
||||
### 1. cryptsetup - LUKS Encryption
|
||||
|
||||
**Purpose**: Handle LUKS encrypted devices
|
||||
|
||||
**Package**: `cryptsetup`
|
||||
|
||||
**Commands Used**:
|
||||
```bash
|
||||
# Close LUKS device
|
||||
cryptsetup close <device-name>
|
||||
|
||||
# Open LUKS device
|
||||
cryptsetup open <device> <name>
|
||||
|
||||
# Create LUKS device
|
||||
cryptsetup luksFormat <device>
|
||||
```
|
||||
|
||||
**Integration**:
|
||||
- TPM2-LUKS support via systemd-cryptenroll
|
||||
- LUKS device detection and management
|
||||
- Encryption key handling
|
||||
|
||||
### 2. grub2-mkconfig - GRUB Configuration
|
||||
|
||||
**Purpose**: Generate GRUB configuration files
|
||||
|
||||
**Package**: `grub2-tools`
|
||||
|
||||
**Commands Used**:
|
||||
```bash
|
||||
# Generate GRUB configuration
|
||||
grub2-mkconfig -o /boot/grub2/grub.cfg
|
||||
|
||||
# Generate EFI configuration
|
||||
grub2-mkconfig -o /boot/efi/EFI/*/grub.cfg
|
||||
```
|
||||
|
||||
**Configuration Files**:
|
||||
- GRUB config: `/etc/default/grub`
|
||||
- GRUB scripts: `/etc/grub.d/*`
|
||||
- Generated config: `/boot/grub2/grub.cfg`
|
||||
|
||||
### 3. dracut - Initramfs Generation
|
||||
|
||||
**Purpose**: Generate initramfs for boot
|
||||
|
||||
**Package**: `dracut`
|
||||
|
||||
**Commands Used**:
|
||||
```bash
|
||||
# Generate initramfs
|
||||
dracut --force /boot/initramfs-<version>.img <version>
|
||||
|
||||
# Regenerate with specific modules
|
||||
dracut --add-drivers <modules> --force
|
||||
```
|
||||
|
||||
**Integration**:
|
||||
- Initramfs generation during container build
|
||||
- Module detection and inclusion
|
||||
- Boot-time filesystem setup
|
||||
|
||||
### 4. Filesystem Creation Commands
|
||||
|
||||
#### mkfs.* - Filesystem Creation
|
||||
|
||||
**Purpose**: Create various filesystem types
|
||||
|
||||
**Package**: `util-linux`, `e2fsprogs`, `xfsprogs`, `btrfs-progs`
|
||||
|
||||
**Commands Used**:
|
||||
```bash
|
||||
# Create XFS filesystem
|
||||
mkfs.xfs /dev/target
|
||||
|
||||
# Create ext4 filesystem
|
||||
mkfs.ext4 /dev/target
|
||||
|
||||
# Create Btrfs filesystem
|
||||
mkfs.btrfs /dev/target
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- Filesystem type determined by install config
|
||||
- Default type: XFS
|
||||
- Configurable via `/usr/lib/bootc/install/*.toml`
|
||||
|
||||
## Command Execution Patterns
|
||||
|
||||
### 1. Task Execution
|
||||
|
||||
```rust
|
||||
// From install.rs - Task execution pattern
|
||||
Task::new("Operation description", "command")
|
||||
.args(["arg1", "arg2"])
|
||||
.cwd(target_directory)?
|
||||
.run()?;
|
||||
```
|
||||
|
||||
### 2. Command with Capture
|
||||
|
||||
```rust
|
||||
// From install.rs - Command with stderr capture
|
||||
Command::new("command")
|
||||
.args(["arg1", "arg2"])
|
||||
.cwd_dir(target_directory)
|
||||
.run_capture_stderr()?;
|
||||
```
|
||||
|
||||
### 3. Async Command Execution
|
||||
|
||||
```rust
|
||||
// From install.rs - Async command execution
|
||||
let result = tokio::task::spawn_blocking(move || {
|
||||
Command::new("command")
|
||||
.args(["arg1", "arg2"])
|
||||
.run()
|
||||
}).await??;
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Command Not Found
|
||||
|
||||
**Detection**: Process exit code 127
|
||||
**Handling**: Check package installation
|
||||
**Recovery**: Install required package
|
||||
|
||||
### 2. Permission Denied
|
||||
|
||||
**Detection**: Process exit code 13
|
||||
**Handling**: Check user privileges
|
||||
**Recovery**: Run with appropriate privileges
|
||||
|
||||
### 3. Resource Exhaustion
|
||||
|
||||
**Detection**: Process exit code 28
|
||||
**Handling**: Check disk space, memory
|
||||
**Recovery**: Free up resources
|
||||
|
||||
### 4. Filesystem Errors
|
||||
|
||||
**Detection**: Process exit code 1
|
||||
**Handling**: Check filesystem state
|
||||
**Recovery**: Repair filesystem if possible
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Command Injection Prevention
|
||||
|
||||
- All commands use structured arguments
|
||||
- No shell interpretation
|
||||
- Input validation and sanitization
|
||||
|
||||
### 2. Privilege Escalation
|
||||
|
||||
- Commands run with minimal required privileges
|
||||
- SELinux context preservation
|
||||
- Capability dropping where possible
|
||||
|
||||
### 3. Resource Limits
|
||||
|
||||
- Disk space validation before operations
|
||||
- Memory usage monitoring
|
||||
- File descriptor limits
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### 1. Parallel Execution
|
||||
|
||||
- Independent commands run in parallel
|
||||
- I/O operations optimized
|
||||
- Resource usage balanced
|
||||
|
||||
### 2. Caching
|
||||
|
||||
- OSTree repository caching
|
||||
- Container image layer caching
|
||||
- Configuration caching
|
||||
|
||||
### 3. Resource Management
|
||||
|
||||
- Temporary file cleanup
|
||||
- Memory usage optimization
|
||||
- Disk I/O optimization
|
||||
|
||||
## Debugging Commands
|
||||
|
||||
### 1. System Information
|
||||
|
||||
```bash
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check bootloader status
|
||||
bootupctl status
|
||||
|
||||
# Check filesystem usage
|
||||
df -h
|
||||
|
||||
# Check mounted filesystems
|
||||
mount | grep -E "(ostree|boot)"
|
||||
```
|
||||
|
||||
### 2. Container Information
|
||||
|
||||
```bash
|
||||
# List container images
|
||||
podman images
|
||||
|
||||
# Check container storage
|
||||
podman system df
|
||||
|
||||
# Inspect container image
|
||||
podman inspect <image>
|
||||
```
|
||||
|
||||
### 3. Boot Information
|
||||
|
||||
```bash
|
||||
# Check kernel command line
|
||||
cat /proc/cmdline
|
||||
|
||||
# Check bootloader entries
|
||||
ls /boot/loader/entries/
|
||||
|
||||
# Check EFI variables
|
||||
efibootmgr -v
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
**OSTree Repository Corruption**:
|
||||
```bash
|
||||
# Repair repository
|
||||
ostree admin init-fs --modern .
|
||||
```
|
||||
|
||||
**Bootloader Installation Failure**:
|
||||
```bash
|
||||
# Reinstall bootloader
|
||||
bootupctl install --force
|
||||
```
|
||||
|
||||
**Filesystem Mount Issues**:
|
||||
```bash
|
||||
# Check mount options
|
||||
mount | grep <device>
|
||||
# Remount with correct options
|
||||
mount -o remount,<options> <device>
|
||||
```
|
||||
|
||||
### 2. Log Analysis
|
||||
|
||||
**Systemd Journal**:
|
||||
```bash
|
||||
# Check bootc logs
|
||||
journalctl -u bootc*
|
||||
|
||||
# Check installation logs
|
||||
journalctl -f | grep bootc
|
||||
```
|
||||
|
||||
**OSTree Logs**:
|
||||
```bash
|
||||
# Check OSTree operations
|
||||
journalctl -u ostree*
|
||||
|
||||
# Check repository operations
|
||||
ostree log <commit>
|
||||
```
|
||||
|
||||
This reference provides comprehensive information about all external commands used by bootc, their purposes, usage patterns, and troubleshooting approaches.
|
||||
282
install/installation-flowchart.md
Normal file
282
install/installation-flowchart.md
Normal file
|
|
@ -0,0 +1,282 @@
|
|||
# bootc Installation Process Flowchart
|
||||
|
||||
## High-Level Installation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc Installation Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Phase 1: Preparation │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ 1.1 Container Environment Detection │
|
||||
│ ├─ Check podman runtime │
|
||||
│ ├─ Validate container execution info │
|
||||
│ └─ Verify privileged access │
|
||||
│ │
|
||||
│ 1.2 Privilege and Namespace Validation │
|
||||
│ ├─ Require --pid=host flag │
|
||||
│ ├─ Validate host user namespace │
|
||||
│ └─ Check root privileges │
|
||||
│ │
|
||||
│ 1.3 SELinux State Management │
|
||||
│ ├─ Detect SELinux policy in container │
|
||||
│ ├─ Check host SELinux state │
|
||||
│ └─ Re-execute if needed for proper labeling │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Phase 2: Filesystem Setup │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ 2.1 OSTree Repository Initialization │
|
||||
│ ├─ Check for existing ostree/repo │
|
||||
│ ├─ Run: ostree admin init-fs --modern . │
|
||||
│ ├─ Configure repository settings │
|
||||
│ └─ Set up stateroot │
|
||||
│ │
|
||||
│ 2.2 Container Image Deployment │
|
||||
│ ├─ Prepare container image for pull │
|
||||
│ ├─ Check disk space requirements │
|
||||
│ ├─ Pull image into OSTree repository │
|
||||
│ ├─ Deploy container to target filesystem │
|
||||
│ └─ Set up deployment metadata │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Phase 3: Bootloader Setup │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ 3.1 Bootupd Integration │
|
||||
│ ├─ Detect target architecture │
|
||||
│ ├─ Configure bootloader type │
|
||||
│ └─ Install via bootupd │
|
||||
│ │
|
||||
│ 3.2 Architecture-Specific Bootloaders │
|
||||
│ ├─ x86_64/aarch64: GRUB2 via bootupd │
|
||||
│ ├─ s390x: zipl │
|
||||
│ └─ Other: Platform-specific │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Phase 4: Kernel Configuration │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ 4.1 Kernel Argument Processing │
|
||||
│ ├─ Extract kargs from OSTree root │
|
||||
│ ├─ Merge install config kargs │
|
||||
│ ├─ Apply container image kargs.d │
|
||||
│ └─ Add CLI-specified kargs │
|
||||
│ │
|
||||
│ 4.2 Initramfs Integration │
|
||||
│ ├─ Locate kernel: /usr/lib/modules/$kver/vmlinuz │
|
||||
│ ├─ Locate initramfs: /usr/lib/modules/$kver/initramfs.img │
|
||||
│ └─ Configure bootloader entries │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Phase 5: Finalization │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ 5.1 Filesystem Optimization │
|
||||
│ ├─ Run: fstrim --quiet-unsupported -v /target │
|
||||
│ ├─ Run: mount -o remount,ro /target │
|
||||
│ └─ Run: fsfreeze -f /target && fsfreeze -u /target │
|
||||
│ │
|
||||
│ 5.2 Cleanup and Validation │
|
||||
│ ├─ Close file descriptors │
|
||||
│ ├─ Unmount target filesystem │
|
||||
│ ├─ Close LUKS devices (if any) │
|
||||
│ └─ Validate installation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Installation Complete │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Detailed Installation Modes
|
||||
|
||||
### 1. to-disk Installation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc install to-disk │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. Validate Target Device │
|
||||
│ ├─ Check if device is block device or file │
|
||||
│ ├─ Handle loopback device if --via-loopback │
|
||||
│ └─ Validate device permissions │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 2. Create Filesystem │
|
||||
│ ├─ Determine filesystem type from config │
|
||||
│ ├─ Run: mkfs.$fstype /dev/target │
|
||||
│ └─ Set up partition table if needed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 3. Mount and Deploy │
|
||||
│ ├─ Mount: /dev/target /mnt │
|
||||
│ ├─ Run: bootc install to-filesystem /mnt │
|
||||
│ └─ Configure kernel arguments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 4. Finalize │
|
||||
│ ├─ Unmount: umount -R /mnt │
|
||||
│ ├─ Close LUKS devices │
|
||||
│ └─ Close loopback devices │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2. to-filesystem Installation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc install to-filesystem │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. Validate Target Filesystem │
|
||||
│ ├─ Check if target is directory │
|
||||
│ ├─ Verify it's a mountpoint │
|
||||
│ ├─ Detect if already OSTree system │
|
||||
│ └─ Handle alongside installation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 2. Clean Target (if needed) │
|
||||
│ ├─ Wipe mode: Remove all contents │
|
||||
│ ├─ Alongside mode: Clean boot directories │
|
||||
│ └─ Default: Require empty root directory │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 3. Deploy Container Image │
|
||||
│ ├─ Initialize OSTree repository │
|
||||
│ ├─ Pull container image │
|
||||
│ ├─ Deploy to target filesystem │
|
||||
│ └─ Configure bootloader │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 4. Finalize │
|
||||
│ ├─ Run: bootc install finalize │
|
||||
│ ├─ Optimize filesystem │
|
||||
│ └─ Validate installation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3. to-existing-root Installation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc install to-existing-root │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. Mount Host Root │
|
||||
│ ├─ Mount: /:/target (if not already mounted) │
|
||||
│ ├─ Detect existing OSTree system │
|
||||
│ └─ Find physical root in /sysroot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 2. Clean Boot Directories │
|
||||
│ ├─ Remove existing bootloader configuration │
|
||||
│ ├─ Clean /boot directory │
|
||||
│ └─ Clean /boot/efi directory (if exists) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 3. Deploy Alongside │
|
||||
│ ├─ Initialize OSTree repository │
|
||||
│ ├─ Deploy container image │
|
||||
│ ├─ Configure bootloader │
|
||||
│ └─ Set up cleanup service │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 4. Setup Cleanup │
|
||||
│ ├─ Create bootc-destructive-cleanup.service │
|
||||
│ ├─ Configure for first boot cleanup │
|
||||
│ └─ Preserve existing data in /sysroot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. Validation Errors │
|
||||
│ ├─ Container environment issues │
|
||||
│ ├─ Privilege/permission errors │
|
||||
│ └─ SELinux policy conflicts │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 2. Resource Errors │
|
||||
│ ├─ Insufficient disk space │
|
||||
│ ├─ Memory allocation failures │
|
||||
│ └─ File descriptor limits │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 3. Deployment Errors │
|
||||
│ ├─ Container image pull failures │
|
||||
│ ├─ OSTree repository issues │
|
||||
│ └─ Bootloader installation failures │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 4. Recovery Actions │
|
||||
│ ├─ Rollback OSTree deployment │
|
||||
│ ├─ Restore bootloader configuration │
|
||||
│ └─ Clean up partial installation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## External Command Dependencies
|
||||
|
||||
### Required Commands
|
||||
- `ostree` - OSTree repository management
|
||||
- `bootupd` - Bootloader management
|
||||
- `podman` - Container runtime
|
||||
- `fstrim` - Filesystem optimization
|
||||
- `mount`/`umount` - Filesystem mounting
|
||||
- `fsfreeze` - Filesystem freeze/thaw
|
||||
|
||||
### Optional Commands
|
||||
- `cryptsetup` - LUKS encryption
|
||||
- `grub2-mkconfig` - GRUB configuration
|
||||
- `dracut` - Initramfs generation
|
||||
- `mkfs.*` - Filesystem creation
|
||||
|
||||
This flowchart provides a comprehensive view of the bootc installation process, showing the sequential phases, decision points, and error handling paths.
|
||||
462
install/source-code-analysis.md
Normal file
462
install/source-code-analysis.md
Normal file
|
|
@ -0,0 +1,462 @@
|
|||
# bootc Installation Source Code Analysis
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a detailed analysis of the bootc installation process based on the source code examination. The analysis covers the key components, data structures, and execution flow of the installation system.
|
||||
|
||||
## Core Data Structures
|
||||
|
||||
### 1. State Management
|
||||
|
||||
```rust
|
||||
// From install.rs:373-390
|
||||
pub(crate) struct State {
|
||||
pub(crate) source: SourceInfo,
|
||||
pub(crate) selinux_state: SELinuxFinalState,
|
||||
pub(crate) config_opts: InstallConfigOpts,
|
||||
pub(crate) target_imgref: ostree_container::OstreeImageReference,
|
||||
pub(crate) prepareroot_config: HashMap<String, String>,
|
||||
pub(crate) install_config: Option<config::InstallConfiguration>,
|
||||
pub(crate) root_ssh_authorized_keys: Option<String>,
|
||||
pub(crate) host_is_container: bool,
|
||||
pub(crate) container_root: Dir,
|
||||
pub(crate) tempdir: TempDir,
|
||||
}
|
||||
```
|
||||
|
||||
**Key Components**:
|
||||
- `source`: Container image information and metadata
|
||||
- `selinux_state`: SELinux configuration state
|
||||
- `target_imgref`: Target image reference for updates
|
||||
- `prepareroot_config`: OSTree prepareroot configuration
|
||||
- `install_config`: Installation-specific configuration
|
||||
|
||||
### 2. Source Information
|
||||
|
||||
```rust
|
||||
// From install.rs:360-370
|
||||
pub(crate) struct SourceInfo {
|
||||
pub(crate) imageref: ostree_container::ImageReference,
|
||||
pub(crate) digest: Option<String>,
|
||||
pub(crate) selinux: bool,
|
||||
pub(crate) in_host_mountns: bool,
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Encapsulates information about the source container image
|
||||
**Key Fields**:
|
||||
- `imageref`: Container image reference
|
||||
- `digest`: Image digest for verification
|
||||
- `selinux`: SELinux policy presence
|
||||
- `in_host_mountns`: Host mount namespace access
|
||||
|
||||
### 3. Root Setup
|
||||
|
||||
```rust
|
||||
// From install.rs:928-942
|
||||
pub(crate) struct RootSetup {
|
||||
#[cfg(feature = "install-to-disk")]
|
||||
luks_device: Option<String>,
|
||||
device_info: bootc_blockdev::PartitionTable,
|
||||
physical_root_path: Utf8PathBuf,
|
||||
physical_root: Dir,
|
||||
rootfs_uuid: Option<String>,
|
||||
skip_finalize: bool,
|
||||
boot: Option<MountSpec>,
|
||||
kargs: Vec<String>,
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Manages target filesystem setup and configuration
|
||||
**Key Fields**:
|
||||
- `device_info`: Partition table information
|
||||
- `physical_root`: Target filesystem directory
|
||||
- `rootfs_uuid`: Root filesystem UUID
|
||||
- `boot`: Boot filesystem mount specification
|
||||
- `kargs`: Kernel arguments
|
||||
|
||||
## Installation Flow Analysis
|
||||
|
||||
### 1. Preparation Phase
|
||||
|
||||
#### Container Environment Detection
|
||||
```rust
|
||||
// From install.rs:520-538
|
||||
pub(crate) fn from_container(
|
||||
root: &Dir,
|
||||
container_info: &ContainerExecutionInfo,
|
||||
) -> Result<Self> {
|
||||
if !container_info.engine.starts_with("podman") {
|
||||
anyhow::bail!("Currently this command only supports being executed via podman");
|
||||
}
|
||||
if container_info.imageid.is_empty() {
|
||||
anyhow::bail!("Invalid empty imageid");
|
||||
}
|
||||
let imageref = ostree_container::ImageReference {
|
||||
transport: ostree_container::Transport::ContainerStorage,
|
||||
name: container_info.image.clone(),
|
||||
};
|
||||
let digest = crate::podman::imageid_to_digest(&container_info.imageid)?;
|
||||
Self::new(imageref, Some(digest), root, true)
|
||||
}
|
||||
```
|
||||
|
||||
**Key Operations**:
|
||||
1. Validate podman runtime
|
||||
2. Extract image reference from container environment
|
||||
3. Resolve image digest
|
||||
4. Detect SELinux policy presence
|
||||
|
||||
#### Privilege Validation
|
||||
```rust
|
||||
// From install.rs:1061-1082
|
||||
fn require_host_pidns() -> Result<()> {
|
||||
if rustix::process::getpid().is_init() {
|
||||
anyhow::bail!("This command must be run with the podman --pid=host flag")
|
||||
}
|
||||
tracing::trace!("OK: we're not pid 1");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn require_host_userns() -> Result<()> {
|
||||
let proc1 = "/proc/1";
|
||||
let pid1_uid = Path::new(proc1)
|
||||
.metadata()
|
||||
.with_context(|| format!("Querying {proc1}"))?
|
||||
.uid();
|
||||
ensure!(pid1_uid == 0, "{proc1} is owned by {pid1_uid}, not zero; this command must be run in the root user namespace");
|
||||
tracing::trace!("OK: we're in a matching user namespace with pid1");
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Steps**:
|
||||
1. Check process ID (not PID 1)
|
||||
2. Verify host user namespace access
|
||||
3. Validate root privileges
|
||||
|
||||
### 2. OSTree Initialization
|
||||
|
||||
#### Repository Setup
|
||||
```rust
|
||||
// From install.rs:591-694
|
||||
async fn initialize_ostree_root(state: &State, root_setup: &RootSetup) -> Result<(Storage, bool)> {
|
||||
let sepolicy = state.load_policy()?;
|
||||
let sepolicy = sepolicy.as_ref();
|
||||
let rootfs_dir = &root_setup.physical_root;
|
||||
let cancellable = gio::Cancellable::NONE;
|
||||
let stateroot = state.stateroot();
|
||||
|
||||
let has_ostree = rootfs_dir.try_exists("ostree/repo")?;
|
||||
if !has_ostree {
|
||||
Task::new("Initializing ostree layout", "ostree")
|
||||
.args(["admin", "init-fs", "--modern", "."])
|
||||
.cwd(rootfs_dir)?
|
||||
.run()?;
|
||||
} else {
|
||||
println!("Reusing extant ostree layout");
|
||||
let path = ".".into();
|
||||
let _ = crate::utils::open_dir_remount_rw(rootfs_dir, path)
|
||||
.context("remounting target as read-write")?;
|
||||
crate::utils::remove_immutability(rootfs_dir, path)?;
|
||||
}
|
||||
// ... repository configuration
|
||||
}
|
||||
```
|
||||
|
||||
**Key Operations**:
|
||||
1. Check for existing OSTree repository
|
||||
2. Initialize repository if needed
|
||||
3. Configure repository settings
|
||||
4. Set up stateroot
|
||||
5. Configure SELinux labeling
|
||||
|
||||
#### Repository Configuration
|
||||
```rust
|
||||
// From install.rs:624-629
|
||||
for (k, v) in DEFAULT_REPO_CONFIG.iter() {
|
||||
Command::new("ostree")
|
||||
.args(["config", "--repo", "ostree/repo", "set", k, v])
|
||||
.cwd_dir(rootfs_dir.try_clone()?)
|
||||
.run_capture_stderr()?;
|
||||
}
|
||||
```
|
||||
|
||||
**Default Configuration**:
|
||||
- `sysroot.bootloader=none`
|
||||
- `sysroot.bootprefix=true`
|
||||
- `sysroot.readonly=true`
|
||||
|
||||
### 3. Container Image Deployment
|
||||
|
||||
#### Image Pulling
|
||||
```rust
|
||||
// From install.rs:755-769
|
||||
let pulled_image = match prepare_for_pull(repo, &spec_imgref, Some(&state.target_imgref))
|
||||
.await?
|
||||
{
|
||||
PreparedPullResult::AlreadyPresent(existing) => existing,
|
||||
PreparedPullResult::Ready(image_meta) => {
|
||||
check_disk_space(root_setup.physical_root.as_fd(), &image_meta, &spec_imgref)?;
|
||||
pull_from_prepared(&spec_imgref, false, ProgressWriter::default(), *image_meta).await?
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. Prepare image for pulling
|
||||
2. Check disk space requirements
|
||||
3. Pull image into OSTree repository
|
||||
4. Handle already present images
|
||||
|
||||
#### Deployment
|
||||
```rust
|
||||
// From install.rs:826-836
|
||||
let mut options = ostree_container::deploy::DeployOpts::default();
|
||||
options.kargs = Some(kargs.as_slice());
|
||||
options.target_imgref = Some(&state.target_imgref);
|
||||
options.proxy_cfg = proxy_cfg;
|
||||
options.skip_completion = true;
|
||||
options.no_clean = has_ostree;
|
||||
let imgstate = crate::utils::async_task_with_spinner(
|
||||
"Deploying container image",
|
||||
ostree_container::deploy::deploy(&sysroot, stateroot, &src_imageref, Some(options)),
|
||||
)
|
||||
.await?;
|
||||
```
|
||||
|
||||
**Deployment Options**:
|
||||
- Kernel arguments configuration
|
||||
- Target image reference
|
||||
- Proxy configuration
|
||||
- Completion skipping
|
||||
- Cleanup control
|
||||
|
||||
### 4. Bootloader Installation
|
||||
|
||||
#### Bootupd Integration
|
||||
```rust
|
||||
// From install.rs:1337-1343
|
||||
crate::bootloader::install_via_bootupd(
|
||||
&rootfs.device_info,
|
||||
&rootfs.physical_root_path,
|
||||
&state.config_opts,
|
||||
&deployment_path.as_str(),
|
||||
)?;
|
||||
```
|
||||
|
||||
**Architecture Support**:
|
||||
- x86_64/aarch64: GRUB2 via bootupd
|
||||
- s390x: zipl implementation
|
||||
- Other: Platform-specific
|
||||
|
||||
### 5. Kernel Argument Processing
|
||||
|
||||
#### Argument Collection
|
||||
```rust
|
||||
// From install.rs:773-825
|
||||
let kargsd = crate::bootc_kargs::get_kargs_from_ostree_root(
|
||||
&sysroot.repo(),
|
||||
merged_ostree_root.downcast_ref().unwrap(),
|
||||
std::env::consts::ARCH,
|
||||
)?;
|
||||
let kargsd = kargsd.iter().map(|s| s.as_str());
|
||||
|
||||
let install_config_kargs = state
|
||||
.install_config
|
||||
.as_ref()
|
||||
.and_then(|c| c.kargs.as_ref())
|
||||
.into_iter()
|
||||
.flatten()
|
||||
.map(|s| s.as_str());
|
||||
|
||||
let kargs = root_setup
|
||||
.kargs
|
||||
.iter()
|
||||
.map(|v| v.as_str())
|
||||
.chain(install_config_kargs)
|
||||
.chain(kargsd)
|
||||
.chain(state.config_opts.karg.iter().flatten().map(|v| v.as_str()))
|
||||
.collect::<Vec<_>>();
|
||||
```
|
||||
|
||||
**Argument Sources (Priority Order)**:
|
||||
1. Root filesystem kargs
|
||||
2. Install configuration kargs
|
||||
3. Container image kargs.d files
|
||||
4. CLI-specified kargs
|
||||
|
||||
### 6. Filesystem Finalization
|
||||
|
||||
#### Optimization Process
|
||||
```rust
|
||||
// From install.rs:1033-1058
|
||||
pub(crate) fn finalize_filesystem(
|
||||
fsname: &str,
|
||||
root: &Dir,
|
||||
path: impl AsRef<Utf8Path>,
|
||||
) -> Result<()> {
|
||||
let path = path.as_ref();
|
||||
// fstrim ensures the underlying block device knows about unused space
|
||||
Task::new(format!("Trimming {fsname}"), "fstrim")
|
||||
.args(["--quiet-unsupported", "-v", path.as_str()])
|
||||
.cwd(root)?
|
||||
.run()?;
|
||||
// Remounting readonly will flush outstanding writes
|
||||
Task::new(format!("Finalizing filesystem {fsname}"), "mount")
|
||||
.cwd(root)?
|
||||
.args(["-o", "remount,ro", path.as_str()])
|
||||
.run()?;
|
||||
// Finally, freezing (and thawing) the filesystem will flush the journal
|
||||
for a in ["-f", "-u"] {
|
||||
Command::new("fsfreeze")
|
||||
.cwd_dir(root.try_clone()?)
|
||||
.args([a, path.as_str()])
|
||||
.run_capture_stderr()?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Finalization Steps**:
|
||||
1. Trim filesystem (fstrim)
|
||||
2. Remount read-only
|
||||
3. Freeze and thaw filesystem
|
||||
4. Flush journal
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
### 1. Contextual Error Handling
|
||||
```rust
|
||||
// From install.rs:393-404
|
||||
#[context("Loading SELinux policy")]
|
||||
pub(crate) fn load_policy(&self) -> Result<Option<ostree::SePolicy>> {
|
||||
if !self.selinux_state.enabled() {
|
||||
return Ok(None);
|
||||
}
|
||||
let r = lsm::new_sepolicy_at(&self.container_root)?
|
||||
.ok_or_else(|| anyhow::anyhow!("SELinux enabled, but no policy found in root"))?;
|
||||
tracing::debug!("Loaded SELinux policy: {}", r.csum().unwrap());
|
||||
Ok(Some(r))
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Resource Validation
|
||||
```rust
|
||||
// From install.rs:696-715
|
||||
fn check_disk_space(
|
||||
repo_fd: impl AsFd,
|
||||
image_meta: &PreparedImportMeta,
|
||||
imgref: &ImageReference,
|
||||
) -> Result<()> {
|
||||
let stat = rustix::fs::fstatvfs(repo_fd)?;
|
||||
let bytes_avail: u64 = stat.f_bsize * stat.f_bavail;
|
||||
|
||||
if image_meta.bytes_to_fetch > bytes_avail {
|
||||
anyhow::bail!(
|
||||
"Insufficient free space for {image} (available: {bytes_avail} required: {bytes_to_fetch})",
|
||||
bytes_avail = ostree_ext::glib::format_size(bytes_avail),
|
||||
bytes_to_fetch = ostree_ext::glib::format_size(image_meta.bytes_to_fetch),
|
||||
image = imgref.image,
|
||||
);
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Graceful Degradation
|
||||
```rust
|
||||
// From install.rs:1001-1029
|
||||
pub(crate) fn reexecute_self_for_selinux_if_needed(
|
||||
srcdata: &SourceInfo,
|
||||
override_disable_selinux: bool,
|
||||
) -> Result<SELinuxFinalState> {
|
||||
if srcdata.selinux {
|
||||
let host_selinux = crate::lsm::selinux_enabled()?;
|
||||
let r = if override_disable_selinux {
|
||||
println!("notice: Target has SELinux enabled, overriding to disable");
|
||||
SELinuxFinalState::ForceTargetDisabled
|
||||
} else if host_selinux {
|
||||
setup_sys_mount("selinuxfs", SELINUXFS)?;
|
||||
let g = crate::lsm::selinux_ensure_install_or_setenforce()?;
|
||||
SELinuxFinalState::Enabled(g)
|
||||
} else {
|
||||
SELinuxFinalState::HostDisabled
|
||||
};
|
||||
Ok(r)
|
||||
} else {
|
||||
Ok(SELinuxFinalState::Disabled)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
### 1. Async Operations
|
||||
```rust
|
||||
// From install.rs:1538-1543
|
||||
let rootfs = tokio::task::spawn_blocking(move || {
|
||||
baseline::install_create_rootfs(&state, block_opts)
|
||||
})
|
||||
.await??;
|
||||
```
|
||||
|
||||
### 2. Parallel Processing
|
||||
- Container image pulling
|
||||
- Filesystem operations
|
||||
- Bootloader installation
|
||||
|
||||
### 3. Resource Management
|
||||
- Temporary directory cleanup
|
||||
- File descriptor management
|
||||
- Memory usage optimization
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. SELinux Integration
|
||||
- Policy detection and loading
|
||||
- Context preservation
|
||||
- Labeling operations
|
||||
|
||||
### 2. Privilege Management
|
||||
- Minimal privilege requirements
|
||||
- Capability dropping
|
||||
- Namespace isolation
|
||||
|
||||
### 3. Input Validation
|
||||
- Command argument validation
|
||||
- Path sanitization
|
||||
- Resource limit enforcement
|
||||
|
||||
## Testing and Validation
|
||||
|
||||
### 1. Unit Tests
|
||||
```rust
|
||||
// From install.rs:2064-2153
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn install_opts_serializable() {
|
||||
let c: InstallToDiskOpts = serde_json::from_value(serde_json::json!({
|
||||
"device": "/dev/vda"
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(c.block_opts.device, "/dev/vda");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Integration Tests
|
||||
- End-to-end installation testing
|
||||
- Error condition testing
|
||||
- Performance testing
|
||||
|
||||
### 3. Validation Steps
|
||||
- Container image integrity
|
||||
- Filesystem compatibility
|
||||
- Bootloader support
|
||||
- Kernel compatibility
|
||||
|
||||
This analysis provides a comprehensive understanding of the bootc installation process from a source code perspective, covering the key components, execution flow, and implementation details.
|
||||
425
install/technical-installation-guide.md
Normal file
425
install/technical-installation-guide.md
Normal file
|
|
@ -0,0 +1,425 @@
|
|||
# bootc Technical Installation Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive technical explanation of how bootc installs container images as bootable operating systems. bootc bridges the gap between OCI/Docker container images and bootable host systems by providing installation mechanisms that create traditional Linux boot environments from container images.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
bootc operates in two distinct modes:
|
||||
|
||||
1. **Container Mode**: When run inside a container (during build), behaves like any other container
|
||||
2. **Host Mode**: When installed to a physical/virtual machine, becomes the bootable OS
|
||||
|
||||
The installation process transforms a container image into a bootable system with:
|
||||
- Bootloader configuration
|
||||
- Kernel and initramfs setup
|
||||
- Root filesystem deployment
|
||||
- OSTree repository initialization
|
||||
|
||||
## Installation Commands
|
||||
|
||||
### Primary Installation Commands
|
||||
|
||||
1. **`bootc install to-disk`** - Direct installation to a block device
|
||||
2. **`bootc install to-filesystem`** - Installation to an existing mounted filesystem
|
||||
3. **`bootc install to-existing-root`** - Convert existing Linux system to bootc
|
||||
4. **`bootc install finalize`** - Post-installation finalization
|
||||
|
||||
### Command Structure
|
||||
|
||||
```bash
|
||||
bootc install [COMMAND] [OPTIONS] [TARGET]
|
||||
```
|
||||
|
||||
## Technical Installation Process
|
||||
|
||||
### Phase 1: Preparation and Validation
|
||||
|
||||
#### 1.1 Container Environment Detection
|
||||
```rust
|
||||
// From install.rs:519-538
|
||||
pub(crate) fn from_container(
|
||||
root: &Dir,
|
||||
container_info: &ContainerExecutionInfo,
|
||||
) -> Result<Self> {
|
||||
if !container_info.engine.starts_with("podman") {
|
||||
anyhow::bail!("Currently this command only supports being executed via podman");
|
||||
}
|
||||
// ... validation logic
|
||||
}
|
||||
```
|
||||
|
||||
**External Commands Required:**
|
||||
- `podman` - Container runtime (required)
|
||||
- `ostree` - OSTree repository management
|
||||
- `bootupd` - Bootloader management
|
||||
|
||||
#### 1.2 Privilege and Namespace Validation
|
||||
```rust
|
||||
// From install.rs:1061-1082
|
||||
fn require_host_pidns() -> Result<()> {
|
||||
if rustix::process::getpid().is_init() {
|
||||
anyhow::bail!("This command must be run with the podman --pid=host flag")
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Required Container Flags:**
|
||||
- `--privileged` - Full host access
|
||||
- `--pid=host` - Host process namespace
|
||||
- `--security-opt label=type:unconfined_t` - SELinux bypass
|
||||
|
||||
#### 1.3 SELinux State Management
|
||||
```rust
|
||||
// From install.rs:1001-1029
|
||||
pub(crate) fn reexecute_self_for_selinux_if_needed(
|
||||
srcdata: &SourceInfo,
|
||||
override_disable_selinux: bool,
|
||||
) -> Result<SELinuxFinalState> {
|
||||
// SELinux policy detection and re-execution logic
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: Filesystem Setup
|
||||
|
||||
#### 2.1 OSTree Repository Initialization
|
||||
```rust
|
||||
// From install.rs:591-694
|
||||
async fn initialize_ostree_root(state: &State, root_setup: &RootSetup) -> Result<(Storage, bool)> {
|
||||
let has_ostree = rootfs_dir.try_exists("ostree/repo")?;
|
||||
if !has_ostree {
|
||||
Task::new("Initializing ostree layout", "ostree")
|
||||
.args(["admin", "init-fs", "--modern", "."])
|
||||
.cwd(rootfs_dir)?
|
||||
.run()?;
|
||||
}
|
||||
// ... repository configuration
|
||||
}
|
||||
```
|
||||
|
||||
**External Commands:**
|
||||
- `ostree admin init-fs --modern` - Initialize OSTree filesystem
|
||||
- `ostree config set` - Configure repository settings
|
||||
|
||||
#### 2.2 Container Image Deployment
|
||||
```rust
|
||||
// From install.rs:718-892
|
||||
async fn install_container(
|
||||
state: &State,
|
||||
root_setup: &RootSetup,
|
||||
sysroot: &ostree::Sysroot,
|
||||
has_ostree: bool,
|
||||
) -> Result<(ostree::Deployment, InstallAleph)> {
|
||||
// Pull container image into OSTree repository
|
||||
let pulled_image = match prepare_for_pull(repo, &spec_imgref, Some(&state.target_imgref)).await? {
|
||||
PreparedPullResult::AlreadyPresent(existing) => existing,
|
||||
PreparedPullResult::Ready(image_meta) => {
|
||||
check_disk_space(root_setup.physical_root.as_fd(), &image_meta, &spec_imgref)?;
|
||||
pull_from_prepared(&spec_imgref, false, ProgressWriter::default(), *image_meta).await?
|
||||
}
|
||||
};
|
||||
// ... deployment logic
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Bootloader Installation
|
||||
|
||||
#### 3.1 Bootupd Integration
|
||||
```rust
|
||||
// From install.rs:1337-1343
|
||||
crate::bootloader::install_via_bootupd(
|
||||
&rootfs.device_info,
|
||||
&rootfs.physical_root_path,
|
||||
&state.config_opts,
|
||||
&deployment_path.as_str(),
|
||||
)?;
|
||||
```
|
||||
|
||||
**External Commands:**
|
||||
- `bootupctl install` - Install bootloader
|
||||
- `bootupctl generate` - Generate bootloader configuration
|
||||
|
||||
#### 3.2 Architecture-Specific Bootloaders
|
||||
- **x86_64/aarch64**: GRUB2 via bootupd
|
||||
- **s390x**: zipl (IBM Z)
|
||||
- **Other**: Platform-specific implementations
|
||||
|
||||
### Phase 4: Kernel and Initramfs Setup
|
||||
|
||||
#### 4.1 Kernel Argument Processing
|
||||
```rust
|
||||
// From install.rs:773-825
|
||||
let kargsd = crate::bootc_kargs::get_kargs_from_ostree_root(
|
||||
&sysroot.repo(),
|
||||
merged_ostree_root.downcast_ref().unwrap(),
|
||||
std::env::consts::ARCH,
|
||||
)?;
|
||||
```
|
||||
|
||||
**Kernel Arguments Sources (in order):**
|
||||
1. Root filesystem kargs
|
||||
2. Install configuration kargs
|
||||
3. Container image kargs.d files
|
||||
4. CLI-specified kargs
|
||||
|
||||
#### 4.2 Initramfs Integration
|
||||
- Kernel location: `/usr/lib/modules/$kver/vmlinuz`
|
||||
- Initramfs location: `/usr/lib/modules/$kver/initramfs.img`
|
||||
- Generated by dracut during container build
|
||||
|
||||
### Phase 5: Filesystem Finalization
|
||||
|
||||
#### 5.1 Filesystem Optimization
|
||||
```rust
|
||||
// From install.rs:1033-1058
|
||||
pub(crate) fn finalize_filesystem(
|
||||
fsname: &str,
|
||||
root: &Dir,
|
||||
path: impl AsRef<Utf8Path>,
|
||||
) -> Result<()> {
|
||||
// fstrim - optimize filesystem
|
||||
Task::new(format!("Trimming {fsname}"), "fstrim")
|
||||
.args(["--quiet-unsupported", "-v", path.as_str()])
|
||||
.cwd(root)?
|
||||
.run()?;
|
||||
|
||||
// Remount read-only
|
||||
Task::new(format!("Finalizing filesystem {fsname}"), "mount")
|
||||
.cwd(root)?
|
||||
.args(["-o", "remount,ro", path.as_str()])
|
||||
.run()?;
|
||||
|
||||
// Freeze/thaw for journal flush
|
||||
for a in ["-f", "-u"] {
|
||||
Command::new("fsfreeze")
|
||||
.cwd_dir(root.try_clone()?)
|
||||
.args([a, path.as_str()])
|
||||
.run_capture_stderr()?;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**External Commands:**
|
||||
- `fstrim` - Trim filesystem for optimization
|
||||
- `mount -o remount,ro` - Remount read-only
|
||||
- `fsfreeze` - Freeze/thaw for journal flush
|
||||
|
||||
## Installation Modes
|
||||
|
||||
### 1. to-disk Installation
|
||||
|
||||
**Process Flow:**
|
||||
1. Create filesystem on target device
|
||||
2. Mount target device
|
||||
3. Deploy container image to mounted filesystem
|
||||
4. Install bootloader
|
||||
5. Unmount and finalize
|
||||
|
||||
**External Commands:**
|
||||
```bash
|
||||
mkfs.$filesystem_type /dev/target
|
||||
mount /dev/target /mnt
|
||||
bootc install to-filesystem --karg=root=UUID=<uuid> /mnt
|
||||
umount /mnt
|
||||
```
|
||||
|
||||
### 2. to-filesystem Installation
|
||||
|
||||
**Process Flow:**
|
||||
1. Validate target filesystem
|
||||
2. Initialize OSTree repository
|
||||
3. Deploy container image
|
||||
4. Configure bootloader
|
||||
5. Finalize filesystem
|
||||
|
||||
**Use Cases:**
|
||||
- Integration with external installers (Anaconda)
|
||||
- Custom partitioning schemes
|
||||
- Cloud image generation
|
||||
|
||||
### 3. to-existing-root Installation
|
||||
|
||||
**Process Flow:**
|
||||
1. Mount host root filesystem
|
||||
2. Clean boot directories
|
||||
3. Deploy alongside existing system
|
||||
4. Configure bootloader
|
||||
5. Set up cleanup service
|
||||
|
||||
**Special Considerations:**
|
||||
- Preserves existing data in `/sysroot`
|
||||
- Requires `--acknowledge-destructive` flag
|
||||
- Sets up cleanup service for first boot
|
||||
|
||||
## External Dependencies
|
||||
|
||||
### Required System Commands
|
||||
|
||||
| Command | Purpose | Package |
|
||||
|---------|---------|---------|
|
||||
| `ostree` | OSTree repository management | ostree |
|
||||
| `bootupd` | Bootloader management | bootupd |
|
||||
| `podman` | Container runtime | podman |
|
||||
| `fstrim` | Filesystem optimization | util-linux |
|
||||
| `mount` | Filesystem mounting | util-linux |
|
||||
| `umount` | Filesystem unmounting | util-linux |
|
||||
| `fsfreeze` | Filesystem freeze/thaw | util-linux |
|
||||
|
||||
### Optional Commands
|
||||
|
||||
| Command | Purpose | Package |
|
||||
|---------|---------|---------|
|
||||
| `cryptsetup` | LUKS encryption | cryptsetup |
|
||||
| `grub2-mkconfig` | GRUB configuration | grub2-tools |
|
||||
| `dracut` | Initramfs generation | dracut |
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### 1. Install Configuration
|
||||
Location: `/usr/lib/bootc/install/*.toml`
|
||||
|
||||
```toml
|
||||
[install.filesystem.root]
|
||||
type = "xfs"
|
||||
|
||||
[install.filesystem.boot]
|
||||
type = "ext4"
|
||||
```
|
||||
|
||||
### 2. Kernel Arguments
|
||||
Location: `/usr/lib/bootc/kargs.d/*.toml`
|
||||
|
||||
```toml
|
||||
[kargs]
|
||||
append = ["console=ttyS0", "quiet"]
|
||||
prepend = ["rd.luks.uuid=12345678-1234-1234-1234-123456789abc"]
|
||||
```
|
||||
|
||||
### 3. OSTree Configuration
|
||||
Location: `ostree/repo/config`
|
||||
|
||||
```ini
|
||||
[core]
|
||||
repo_version=1
|
||||
mode=bare
|
||||
|
||||
[sysroot]
|
||||
bootloader=none
|
||||
bootprefix=true
|
||||
readonly=true
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. SELinux Integration
|
||||
- Automatic policy detection
|
||||
- Re-execution for proper labeling
|
||||
- Target system SELinux configuration
|
||||
|
||||
### 2. Container Security
|
||||
- Requires privileged container execution
|
||||
- Host mount namespace access
|
||||
- Device access for installation
|
||||
|
||||
### 3. Filesystem Security
|
||||
- Atomic operations where possible
|
||||
- Proper file permissions
|
||||
- SELinux labeling
|
||||
|
||||
## Error Handling and Recovery
|
||||
|
||||
### 1. Disk Space Validation
|
||||
```rust
|
||||
// From install.rs:696-715
|
||||
fn check_disk_space(
|
||||
repo_fd: impl AsFd,
|
||||
image_meta: &PreparedImportMeta,
|
||||
imgref: &ImageReference,
|
||||
) -> Result<()> {
|
||||
let stat = rustix::fs::fstatvfs(repo_fd)?;
|
||||
let bytes_avail: u64 = stat.f_bsize * stat.f_bavail;
|
||||
|
||||
if image_meta.bytes_to_fetch > bytes_avail {
|
||||
anyhow::bail!(
|
||||
"Insufficient free space for {image} (available: {bytes_avail} required: {bytes_to_fetch})",
|
||||
// ... error details
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Rollback Capability
|
||||
- OSTree provides atomic rollback
|
||||
- Bootloader configuration backup
|
||||
- Deployment state tracking
|
||||
|
||||
### 3. Validation Steps
|
||||
- Container image integrity
|
||||
- Filesystem compatibility
|
||||
- Bootloader support
|
||||
- Kernel compatibility
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Parallel Operations
|
||||
- Container image pulling
|
||||
- Filesystem operations
|
||||
- Bootloader installation
|
||||
|
||||
### 2. Disk I/O Optimization
|
||||
- OSTree repository configuration
|
||||
- Filesystem trimming
|
||||
- Write optimization
|
||||
|
||||
### 3. Memory Usage
|
||||
- Container image caching
|
||||
- OSTree repository management
|
||||
- Temporary file handling
|
||||
|
||||
## Debugging and Troubleshooting
|
||||
|
||||
### 1. Logging
|
||||
- Structured logging with tracing
|
||||
- Journal integration
|
||||
- Progress reporting
|
||||
|
||||
### 2. Common Issues
|
||||
- Insufficient disk space
|
||||
- SELinux policy conflicts
|
||||
- Bootloader installation failures
|
||||
- Container image access issues
|
||||
|
||||
### 3. Debug Commands
|
||||
```bash
|
||||
# Check OSTree repository
|
||||
ostree admin status
|
||||
|
||||
# Verify bootloader
|
||||
bootupctl status
|
||||
|
||||
# Check container image
|
||||
podman images
|
||||
|
||||
# Validate filesystem
|
||||
lsblk -f
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
- Dynamic ConfigMap injection
|
||||
- Enhanced rollback mechanisms
|
||||
- Multi-architecture support
|
||||
- Cloud integration improvements
|
||||
|
||||
### 2. API Evolution
|
||||
- Stable CLI interface
|
||||
- REST API for management
|
||||
- Configuration management
|
||||
- Monitoring integration
|
||||
|
||||
---
|
||||
|
||||
This technical guide provides the foundation for understanding bootc's installation process. The system is designed to be robust, secure, and maintainable while providing the flexibility needed for various deployment scenarios.
|
||||
75
installation.md
Normal file
75
installation.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# Installation
|
||||
|
||||
## Base Images
|
||||
|
||||
Many users will be more interested in base (container) images for Debian.
|
||||
|
||||
## Debian
|
||||
|
||||
Currently, the Debian bootc project is focused on providing bootc support for Debian-based systems.
|
||||
|
||||
For pre-built base images, any Debian derivative can be converted to use bootc. However, since bootc is not yet available as a Debian package, you'll need to compile it from source.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Debian 14 (Forky) or later
|
||||
- Systemd as the init system
|
||||
- Root access for installation
|
||||
- Development tools and dependencies for compiling bootc
|
||||
|
||||
### Installation Steps
|
||||
|
||||
1. **Install build dependencies:**
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y build-essential git pkg-config libostree-dev libglib2.0-dev libgpgme-dev libseccomp-dev
|
||||
```
|
||||
|
||||
2. **Install runtime dependencies:**
|
||||
```bash
|
||||
sudo apt install -y ostree podman
|
||||
```
|
||||
|
||||
3. **Clone and build bootc:**
|
||||
```bash
|
||||
git clone https://github.com/containers/bootc.git
|
||||
cd bootc
|
||||
make
|
||||
sudo make install
|
||||
```
|
||||
|
||||
4. **Verify installation:**
|
||||
```bash
|
||||
bootc --version
|
||||
```
|
||||
|
||||
### Converting Existing Debian Systems
|
||||
|
||||
Converting an existing Debian system to use bootc requires careful planning:
|
||||
|
||||
1. **Backup your system** - This is a major change to how your OS updates work
|
||||
2. **Prepare a bootc-compatible base image** - This should be based on your current Debian installation
|
||||
3. **Test the conversion process** - Use a virtual machine or test system first
|
||||
4. **Execute the conversion** - Follow the bootc conversion guide for Debian
|
||||
|
||||
### Debian-Specific Considerations
|
||||
|
||||
- **Source Compilation**: Since bootc is not packaged for Debian yet, you'll need to compile from source
|
||||
- **Package Management**: bootc works alongside `apt` for application packages while managing the base OS through container images
|
||||
- **Configuration**: System configuration follows Debian conventions with `/etc` for machine-local settings
|
||||
- **Services**: systemd services work normally, with bootc managing the base OS layer
|
||||
- **Updates**: OS updates are handled through bootc, while application updates continue to use `apt`
|
||||
- **Development Status**: This is experimental software - use with caution in production environments
|
||||
|
||||
## Other Distributions
|
||||
|
||||
bootc itself is not tied to Debian derivatives; this issue tracks the main blocker for other distributions. However, Debian provides a solid foundation for bootc implementation due to its:
|
||||
|
||||
- Mature package management system
|
||||
- Strong systemd integration
|
||||
- Extensive hardware support
|
||||
- Long-term support releases
|
||||
|
||||
---
|
||||
|
||||
The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.
|
||||
733
internals/bootc-internals-architecture.md
Normal file
733
internals/bootc-internals-architecture.md
Normal file
|
|
@ -0,0 +1,733 @@
|
|||
# bootc internals - Architecture and Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a deep dive into the architecture and implementation details of the `bootc internals` system, covering the Rust code structure, design patterns, and integration points.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The bootc internals system is built on a modular architecture that provides internal-only operations for system maintenance, debugging, and integration. The system is designed to be:
|
||||
|
||||
- **Hidden**: Commands are not visible in regular help output
|
||||
- **Internal**: Intended for system administrators and developers
|
||||
- **Modular**: Each command is self-contained with clear responsibilities
|
||||
- **Integrated**: Seamlessly integrates with existing bootc infrastructure
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Command Structure
|
||||
|
||||
The internals system is built around the `InternalsOpts` enum, which defines all available internal commands:
|
||||
|
||||
```rust
|
||||
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
|
||||
pub(crate) enum InternalsOpts {
|
||||
SystemdGenerator {
|
||||
normal_dir: Utf8PathBuf,
|
||||
early_dir: Option<Utf8PathBuf>,
|
||||
late_dir: Option<Utf8PathBuf>,
|
||||
},
|
||||
FixupEtcFstab,
|
||||
PrintJsonSchema {
|
||||
#[clap(long)]
|
||||
of: SchemaType,
|
||||
},
|
||||
#[clap(subcommand)]
|
||||
Fsverity(FsverityOpts),
|
||||
Fsck,
|
||||
Cleanup,
|
||||
Relabel {
|
||||
#[clap(long)]
|
||||
as_path: Option<Utf8PathBuf>,
|
||||
path: Utf8PathBuf,
|
||||
},
|
||||
OstreeExt { args: Vec<OsString> },
|
||||
Cfs { args: Vec<OsString> },
|
||||
OstreeContainer { args: Vec<OsString> },
|
||||
TestComposefs,
|
||||
LoopbackCleanupHelper { device: String },
|
||||
AllocateCleanupLoopback { file_path: Utf8PathBuf },
|
||||
BootcInstallCompletion { sysroot: Utf8PathBuf, stateroot: String },
|
||||
Reboot,
|
||||
#[cfg(feature = "rhsm")]
|
||||
PublishRhsmFacts,
|
||||
#[cfg(feature = "docgen")]
|
||||
DumpCliJson,
|
||||
DirDiff {
|
||||
pristine_etc: Utf8PathBuf,
|
||||
current_etc: Utf8PathBuf,
|
||||
new_etc: Utf8PathBuf,
|
||||
perform_merge: bool,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Command Routing
|
||||
|
||||
Commands are routed through the main CLI dispatcher in `cli.rs`:
|
||||
|
||||
```rust
|
||||
match opt {
|
||||
Opt::Internals(opts) => match opts {
|
||||
InternalsOpts::SystemdGenerator { normal_dir, early_dir, late_dir } => {
|
||||
let unit_dir = &Dir::open_ambient_dir(normal_dir, cap_std::ambient_authority())?;
|
||||
crate::generator::generator(root, unit_dir)
|
||||
}
|
||||
InternalsOpts::Fsck => {
|
||||
let sysroot = &get_storage().await?;
|
||||
crate::fsck::fsck(&sysroot, std::io::stdout().lock()).await?;
|
||||
Ok(())
|
||||
}
|
||||
// ... other commands
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Module Architecture
|
||||
|
||||
### 1. Generator Module (`generator.rs`)
|
||||
|
||||
**Purpose**: Systemd integration and unit generation
|
||||
|
||||
**Key Functions**:
|
||||
- `fstab_generator_impl()` - Generate fstab editor service
|
||||
- `generate_fstab_editor()` - Create systemd unit file
|
||||
- `generator()` - Main generator entry point
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub(crate) fn fstab_generator_impl(root: &Dir, unit_dir: &Dir) -> Result<bool> {
|
||||
// Check if system is ostree-booted
|
||||
if !is_ostree_booted_in(root)? {
|
||||
return Ok(false);
|
||||
}
|
||||
|
||||
// Check /etc/fstab for anaconda stamp
|
||||
if let Some(fd) = root.open_optional("etc/fstab")? {
|
||||
let mut from_anaconda = false;
|
||||
for line in fd.lines() {
|
||||
let line = line?;
|
||||
if line.contains(BOOTC_EDITED_STAMP) {
|
||||
return Ok(false); // Already processed
|
||||
}
|
||||
if line.contains(FSTAB_ANACONDA_STAMP) {
|
||||
from_anaconda = true;
|
||||
}
|
||||
}
|
||||
|
||||
if from_anaconda {
|
||||
generate_fstab_editor(unit_dir)?;
|
||||
return Ok(true);
|
||||
}
|
||||
}
|
||||
Ok(false)
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `ostree_ext::container_utils::is_ostree_booted_in`
|
||||
- `cap_std::fs::Dir`
|
||||
- `rustix::fs::StatVfsMountFlags`
|
||||
|
||||
### 2. Filesystem Check Module (`fsck.rs`)
|
||||
|
||||
**Purpose**: System consistency checking
|
||||
|
||||
**Key Functions**:
|
||||
- `fsck()` - Main consistency check entry point
|
||||
- `fsck_ok()` - Return success result
|
||||
- `fsck_err()` - Return error result
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub async fn fsck(sysroot: &Storage, mut out: impl Write) -> Result<()> {
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = ostree.repo();
|
||||
|
||||
// Run all registered fsck checks
|
||||
for check in FSCK_CHECKS {
|
||||
match check(sysroot).await {
|
||||
Ok(Ok(())) => writeln!(out, "✓ {}", check.name())?,
|
||||
Ok(Err(e)) => writeln!(out, "✗ {}: {}", check.name(), e)?,
|
||||
Err(e) => writeln!(out, "✗ {}: {}", check.name(), e)?,
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `linkme::distributed_slice` - For check registration
|
||||
- `ostree_ext::composefs` - For composefs operations
|
||||
- `ostree_ext::ostree` - For OSTree operations
|
||||
|
||||
### 3. Composefs Control Module (`cfsctl.rs`)
|
||||
|
||||
**Purpose**: Composefs repository management
|
||||
|
||||
**Key Functions**:
|
||||
- `run_from_iter()` - Parse and execute cfsctl commands
|
||||
- `App::parse()` - Parse command line arguments
|
||||
- `Command` enum - Define available commands
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub async fn run_from_iter<I>(args: I) -> Result<()>
|
||||
where
|
||||
I: IntoIterator<Item = impl AsRef<OsStr>>,
|
||||
{
|
||||
let app = App::parse_from(args);
|
||||
let repo = if app.user {
|
||||
Repository::open_user()?
|
||||
} else if app.system {
|
||||
Repository::open_system()?
|
||||
} else if let Some(repo_path) = app.repo {
|
||||
Repository::open(repo_path)?
|
||||
} else {
|
||||
Repository::open_default()?
|
||||
};
|
||||
|
||||
match app.cmd {
|
||||
Command::Oci(oci_cmd) => match oci_cmd {
|
||||
OciCommand::ImportLayer { sha256, name } => {
|
||||
// Import layer implementation
|
||||
}
|
||||
OciCommand::LsLayer { name } => {
|
||||
// List layer implementation
|
||||
}
|
||||
// ... other OCI commands
|
||||
}
|
||||
Command::CreateFs { name, output } => {
|
||||
// Create filesystem implementation
|
||||
}
|
||||
Command::WriteBoot { name, output } => {
|
||||
// Write boot entries implementation
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `composefs::repository::Repository`
|
||||
- `composefs::fsverity::FsVerityHashValue`
|
||||
- `composefs_boot::write_boot`
|
||||
|
||||
### 4. Deploy Module (`deploy.rs`)
|
||||
|
||||
**Purpose**: Deployment operations and cleanup
|
||||
|
||||
**Key Functions**:
|
||||
- `fixup_etc_fstab()` - Fix /etc/fstab for composefs
|
||||
- `cleanup()` - Perform system cleanup
|
||||
- `switch_origin_inplace()` - In-place origin switching
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub(crate) fn fixup_etc_fstab(root: &Dir) -> Result<()> {
|
||||
let fstab_path = root.open("etc/fstab")?;
|
||||
let mut fstab_content = String::new();
|
||||
fstab_path.read_to_string(&mut fstab_content)?;
|
||||
|
||||
let mut lines = fstab_content.lines().collect::<Vec<_>>();
|
||||
let mut modified = false;
|
||||
|
||||
for line in lines.iter_mut() {
|
||||
if line.contains("ro") && !line.contains("ro,") {
|
||||
*line = line.replace("ro", "ro,");
|
||||
modified = true;
|
||||
}
|
||||
}
|
||||
|
||||
if modified {
|
||||
let mut fstab_file = root.create("etc/fstab")?;
|
||||
for line in lines {
|
||||
writeln!(fstab_file, "{}", line)?;
|
||||
}
|
||||
writeln!(fstab_file, "# {}", BOOTC_EDITED_STAMP)?;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `cap_std::fs::Dir`
|
||||
- `std::io::Write`
|
||||
- `ostree_ext::ostree`
|
||||
|
||||
### 5. Block Device Module (`blockdev.rs`)
|
||||
|
||||
**Purpose**: Loopback device management
|
||||
|
||||
**Key Functions**:
|
||||
- `LoopbackDevice::new()` - Create loopback device
|
||||
- `run_loopback_cleanup_helper()` - Cleanup helper
|
||||
- `run_allocate_cleanup_loopback()` - Test allocation
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub struct LoopbackDevice {
|
||||
device: String,
|
||||
file: PathBuf,
|
||||
}
|
||||
|
||||
impl LoopbackDevice {
|
||||
pub fn new(file_path: &Path) -> Result<Self> {
|
||||
let output = Command::new("losetup")
|
||||
.args(["-f", "--show", file_path.to_str().unwrap()])
|
||||
.output()?;
|
||||
|
||||
if !output.status.success() {
|
||||
return Err(anyhow::anyhow!("Failed to create loopback device"));
|
||||
}
|
||||
|
||||
let device = String::from_utf8(output.stdout)?;
|
||||
let device = device.trim().to_string();
|
||||
|
||||
Ok(Self {
|
||||
device,
|
||||
file: file_path.to_path_buf(),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn path(&self) -> &str {
|
||||
&self.device
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for LoopbackDevice {
|
||||
fn drop(&mut self) {
|
||||
let _ = Command::new("losetup")
|
||||
.args(["-d", &self.device])
|
||||
.output();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `std::process::Command`
|
||||
- `std::path::Path`
|
||||
- `anyhow::Result`
|
||||
|
||||
## Design Patterns
|
||||
|
||||
### 1. Command Pattern
|
||||
|
||||
Each internals command follows the command pattern, encapsulating a request as an object:
|
||||
|
||||
```rust
|
||||
trait InternalCommand {
|
||||
fn execute(&self) -> Result<()>;
|
||||
}
|
||||
|
||||
impl InternalCommand for SystemdGenerator {
|
||||
fn execute(&self) -> Result<()> {
|
||||
let unit_dir = &Dir::open_ambient_dir(&self.normal_dir, cap_std::ambient_authority())?;
|
||||
crate::generator::generator(&self.root, unit_dir)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Strategy Pattern
|
||||
|
||||
Different commands use different strategies for execution:
|
||||
|
||||
```rust
|
||||
enum ExecutionStrategy {
|
||||
Direct(DirectCommand),
|
||||
Proxy(ProxyCommand),
|
||||
Generator(GeneratorCommand),
|
||||
Test(TestCommand),
|
||||
}
|
||||
|
||||
impl ExecutionStrategy {
|
||||
fn execute(&self) -> Result<()> {
|
||||
match self {
|
||||
ExecutionStrategy::Direct(cmd) => cmd.execute_direct(),
|
||||
ExecutionStrategy::Proxy(cmd) => cmd.execute_proxy(),
|
||||
ExecutionStrategy::Generator(cmd) => cmd.execute_generator(),
|
||||
ExecutionStrategy::Test(cmd) => cmd.execute_test(),
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Factory Pattern
|
||||
|
||||
Commands are created using a factory pattern:
|
||||
|
||||
```rust
|
||||
struct CommandFactory;
|
||||
|
||||
impl CommandFactory {
|
||||
fn create_command(opts: &InternalsOpts) -> Box<dyn InternalCommand> {
|
||||
match opts {
|
||||
InternalsOpts::SystemdGenerator { .. } => {
|
||||
Box::new(SystemdGenerator::new(opts))
|
||||
}
|
||||
InternalsOpts::Fsck => {
|
||||
Box::new(FsckCommand::new())
|
||||
}
|
||||
// ... other commands
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Error Types
|
||||
|
||||
The system uses a hierarchical error structure:
|
||||
|
||||
```rust
|
||||
#[derive(thiserror::Error, Debug)]
|
||||
pub enum InternalError {
|
||||
#[error("System error: {0}")]
|
||||
System(String),
|
||||
|
||||
#[error("Permission error: {0}")]
|
||||
Permission(String),
|
||||
|
||||
#[error("Resource error: {0}")]
|
||||
Resource(String),
|
||||
|
||||
#[error("Configuration error: {0}")]
|
||||
Configuration(String),
|
||||
}
|
||||
|
||||
impl From<std::io::Error> for InternalError {
|
||||
fn from(err: std::io::Error) -> Self {
|
||||
InternalError::System(err.to_string())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Error Context
|
||||
|
||||
All operations use error context for better debugging:
|
||||
|
||||
```rust
|
||||
#[context("Systemd generator")]
|
||||
pub(crate) fn generator(root: &Dir, unit_dir: &Dir) -> Result<()> {
|
||||
// Implementation with automatic error context
|
||||
}
|
||||
|
||||
#[context("Filesystem check")]
|
||||
pub async fn fsck(sysroot: &Storage, out: impl Write) -> Result<()> {
|
||||
// Implementation with automatic error context
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Error Recovery
|
||||
|
||||
The system implements error recovery strategies:
|
||||
|
||||
```rust
|
||||
pub async fn execute_with_retry<F, T>(mut operation: F, max_retries: usize) -> Result<T>
|
||||
where
|
||||
F: FnMut() -> Result<T>,
|
||||
{
|
||||
let mut last_error = None;
|
||||
|
||||
for attempt in 0..max_retries {
|
||||
match operation() {
|
||||
Ok(result) => return Ok(result),
|
||||
Err(e) => {
|
||||
last_error = Some(e);
|
||||
if attempt < max_retries - 1 {
|
||||
tokio::time::sleep(Duration::from_millis(100 * (attempt + 1) as u64)).await;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Err(last_error.unwrap())
|
||||
}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Privilege Escalation
|
||||
|
||||
All internals commands require root privileges:
|
||||
|
||||
```rust
|
||||
pub(crate) fn require_root(is_container: bool) -> Result<()> {
|
||||
ensure!(
|
||||
rustix::process::getuid().is_root(),
|
||||
if is_container {
|
||||
"The user inside the container from which you are running this command must be root"
|
||||
} else {
|
||||
"This command must be executed as the root user"
|
||||
}
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Input Validation
|
||||
|
||||
All inputs are validated before processing:
|
||||
|
||||
```rust
|
||||
pub(crate) fn validate_path(path: &Path) -> Result<()> {
|
||||
// Check for path traversal
|
||||
if path.components().any(|c| c == Component::ParentDir) {
|
||||
return Err(anyhow::anyhow!("Path traversal detected"));
|
||||
}
|
||||
|
||||
// Check for absolute paths
|
||||
if !path.is_absolute() {
|
||||
return Err(anyhow::anyhow!("Path must be absolute"));
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Resource Limits
|
||||
|
||||
Operations are limited to prevent resource exhaustion:
|
||||
|
||||
```rust
|
||||
pub(crate) fn with_resource_limits<F, T>(operation: F) -> Result<T>
|
||||
where
|
||||
F: FnOnce() -> Result<T>,
|
||||
{
|
||||
// Set memory limit
|
||||
let memory_limit = 1024 * 1024 * 1024; // 1GB
|
||||
let mut limits = rlimit::ResourceLimits::default();
|
||||
limits.set_memory_limit(memory_limit)?;
|
||||
limits.apply()?;
|
||||
|
||||
// Execute operation
|
||||
operation()
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### 1. Async Operations
|
||||
|
||||
All I/O operations are asynchronous:
|
||||
|
||||
```rust
|
||||
pub async fn cleanup_async(sysroot: &Storage) -> Result<()> {
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = ostree.repo();
|
||||
|
||||
// Async repository operations
|
||||
let deployments = repo.list_deployments().await?;
|
||||
let unused_deployments = find_unused_deployments(deployments).await?;
|
||||
|
||||
for deployment in unused_deployments {
|
||||
repo.remove_deployment(deployment).await?;
|
||||
}
|
||||
|
||||
// Async garbage collection
|
||||
repo.garbage_collect().await?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Parallel Processing
|
||||
|
||||
Operations that can be parallelized are:
|
||||
|
||||
```rust
|
||||
pub async fn parallel_checks(sysroot: &Storage) -> Result<()> {
|
||||
let checks = vec![
|
||||
check_ostree_repo(sysroot),
|
||||
check_composefs_repo(sysroot),
|
||||
check_deployments(sysroot),
|
||||
check_configuration(sysroot),
|
||||
];
|
||||
|
||||
let results = futures::future::join_all(checks).await;
|
||||
|
||||
for result in results {
|
||||
result?;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Caching
|
||||
|
||||
Frequently accessed data is cached:
|
||||
|
||||
```rust
|
||||
pub struct Cache {
|
||||
deployments: Option<Vec<Deployment>>,
|
||||
images: Option<Vec<Image>>,
|
||||
last_update: Option<Instant>,
|
||||
}
|
||||
|
||||
impl Cache {
|
||||
pub async fn get_deployments(&mut self, sysroot: &Storage) -> Result<&Vec<Deployment>> {
|
||||
if self.deployments.is_none() || self.should_refresh() {
|
||||
self.deployments = Some(sysroot.get_deployments().await?);
|
||||
self.last_update = Some(Instant::now());
|
||||
}
|
||||
|
||||
Ok(self.deployments.as_ref().unwrap())
|
||||
}
|
||||
|
||||
fn should_refresh(&self) -> bool {
|
||||
self.last_update
|
||||
.map(|last| last.elapsed() > Duration::from_secs(60))
|
||||
.unwrap_or(true)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### 1. Unit Tests
|
||||
|
||||
Each module has comprehensive unit tests:
|
||||
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_systemd_generator() {
|
||||
let temp_dir = tempfile::tempdir().unwrap();
|
||||
let unit_dir = Dir::open_ambient_dir(temp_dir.path(), cap_std::ambient_authority()).unwrap();
|
||||
|
||||
// Test generator functionality
|
||||
let result = fstab_generator_impl(&root, &unit_dir);
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_fsck_operations() {
|
||||
let temp_sysroot = create_test_sysroot().unwrap();
|
||||
|
||||
// Test fsck functionality
|
||||
let result = fsck(&temp_sysroot, Vec::new()).await;
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Integration Tests
|
||||
|
||||
End-to-end integration tests:
|
||||
|
||||
```rust
|
||||
#[tokio::test]
|
||||
async fn test_internals_integration() {
|
||||
// Setup test environment
|
||||
let test_env = TestEnvironment::new().await.unwrap();
|
||||
|
||||
// Test systemd generator
|
||||
let result = test_env.run_internals_command("systemd-generator", &["/tmp"]).await;
|
||||
assert!(result.is_ok());
|
||||
|
||||
// Test fsck
|
||||
let result = test_env.run_internals_command("fsck", &[]).await;
|
||||
assert!(result.is_ok());
|
||||
|
||||
// Test cleanup
|
||||
let result = test_env.run_internals_command("cleanup", &[]).await;
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Performance Tests
|
||||
|
||||
Performance benchmarks:
|
||||
|
||||
```rust
|
||||
#[bench]
|
||||
fn bench_fsck_operations(b: &mut Bencher) {
|
||||
let sysroot = create_test_sysroot().unwrap();
|
||||
|
||||
b.iter(|| {
|
||||
let rt = tokio::runtime::Runtime::new().unwrap();
|
||||
rt.block_on(fsck(&sysroot, Vec::new()))
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Plugin System
|
||||
|
||||
A plugin system for extending internals functionality:
|
||||
|
||||
```rust
|
||||
pub trait InternalPlugin {
|
||||
fn name(&self) -> &str;
|
||||
fn execute(&self, args: &[String]) -> Result<()>;
|
||||
fn help(&self) -> &str;
|
||||
}
|
||||
|
||||
pub struct PluginManager {
|
||||
plugins: Vec<Box<dyn InternalPlugin>>,
|
||||
}
|
||||
|
||||
impl PluginManager {
|
||||
pub fn register_plugin(&mut self, plugin: Box<dyn InternalPlugin>) {
|
||||
self.plugins.push(plugin);
|
||||
}
|
||||
|
||||
pub fn execute_plugin(&self, name: &str, args: &[String]) -> Result<()> {
|
||||
let plugin = self.plugins.iter()
|
||||
.find(|p| p.name() == name)
|
||||
.ok_or_else(|| anyhow::anyhow!("Plugin not found: {}", name))?;
|
||||
|
||||
plugin.execute(args)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Configuration Management
|
||||
|
||||
Centralized configuration for internals commands:
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
pub struct InternalsConfig {
|
||||
pub fsck: FsckConfig,
|
||||
pub cleanup: CleanupConfig,
|
||||
pub generator: GeneratorConfig,
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
pub struct FsckConfig {
|
||||
pub enabled_checks: Vec<String>,
|
||||
pub timeout_seconds: u64,
|
||||
pub parallel_checks: bool,
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Monitoring Integration
|
||||
|
||||
Integration with monitoring systems:
|
||||
|
||||
```rust
|
||||
pub trait MetricsCollector {
|
||||
fn record_command_execution(&self, command: &str, duration: Duration, success: bool);
|
||||
fn record_error(&self, command: &str, error: &str);
|
||||
fn record_resource_usage(&self, command: &str, memory: u64, cpu: f64);
|
||||
}
|
||||
|
||||
pub struct PrometheusCollector {
|
||||
registry: Registry,
|
||||
}
|
||||
|
||||
impl MetricsCollector for PrometheusCollector {
|
||||
fn record_command_execution(&self, command: &str, duration: Duration, success: bool) {
|
||||
// Record metrics in Prometheus format
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This architecture document provides a comprehensive understanding of the bootc internals system's design, implementation, and future direction.
|
||||
727
internals/bootc-internals-examples-troubleshooting.md
Normal file
727
internals/bootc-internals-examples-troubleshooting.md
Normal file
|
|
@ -0,0 +1,727 @@
|
|||
# bootc internals - Examples and Troubleshooting
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides practical examples and troubleshooting guidance for the `bootc internals` system, covering common use cases, error scenarios, and debugging techniques.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. System Maintenance
|
||||
|
||||
#### Daily Cleanup Operations
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Daily cleanup script for bootc systems
|
||||
|
||||
# Run filesystem consistency check
|
||||
echo "Running filesystem consistency check..."
|
||||
bootc internals fsck
|
||||
|
||||
# Perform cleanup operations
|
||||
echo "Performing cleanup operations..."
|
||||
bootc internals cleanup
|
||||
|
||||
# Check system status
|
||||
echo "Checking system status..."
|
||||
bootc status
|
||||
|
||||
# Log results
|
||||
echo "Maintenance completed at $(date)" >> /var/log/bootc-maintenance.log
|
||||
```
|
||||
|
||||
#### Weekly Deep Cleanup
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Weekly deep cleanup script
|
||||
|
||||
# Run comprehensive fsck
|
||||
echo "Running comprehensive filesystem check..."
|
||||
bootc internals fsck --verbose
|
||||
|
||||
# Clean up old deployments
|
||||
echo "Cleaning up old deployments..."
|
||||
bootc internals cleanup --aggressive
|
||||
|
||||
# Check for unused images
|
||||
echo "Checking for unused images..."
|
||||
bootc image list --unused
|
||||
|
||||
# Remove unused images
|
||||
echo "Removing unused images..."
|
||||
bootc image prune
|
||||
|
||||
# Log results
|
||||
echo "Deep cleanup completed at $(date)" >> /var/log/bootc-maintenance.log
|
||||
```
|
||||
|
||||
### 2. Development and Testing
|
||||
|
||||
#### Test Environment Setup
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Setup test environment for bootc development
|
||||
|
||||
# Create test directory
|
||||
mkdir -p /tmp/bootc-test
|
||||
cd /tmp/bootc-test
|
||||
|
||||
# Test composefs repository
|
||||
echo "Testing composefs repository..."
|
||||
bootc internals test-composefs
|
||||
|
||||
# Test loopback device allocation
|
||||
echo "Testing loopback device allocation..."
|
||||
bootc internals allocate-cleanup-loopback --file-path /tmp/test-image.img
|
||||
|
||||
# Test directory diff functionality
|
||||
echo "Testing directory diff..."
|
||||
bootc internals dir-diff \
|
||||
--pristine-etc /tmp/pristine-etc \
|
||||
--current-etc /tmp/current-etc \
|
||||
--new-etc /tmp/new-etc \
|
||||
--perform-merge
|
||||
|
||||
# Clean up test environment
|
||||
echo "Cleaning up test environment..."
|
||||
rm -rf /tmp/bootc-test
|
||||
```
|
||||
|
||||
#### Container Image Testing
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Test container image operations
|
||||
|
||||
# Test image pull
|
||||
echo "Testing image pull..."
|
||||
bootc internals ostree-ext container pull quay.io/myorg/test-image:latest
|
||||
|
||||
# Test image build
|
||||
echo "Testing image build..."
|
||||
bootc internals ostree-ext container build /path/to/containerfile
|
||||
|
||||
# Test image verification
|
||||
echo "Testing image verification..."
|
||||
bootc internals fsverity measure /path/to/image
|
||||
|
||||
# Test image deployment
|
||||
echo "Testing image deployment..."
|
||||
bootc internals ostree-ext container deploy quay.io/myorg/test-image:latest
|
||||
```
|
||||
|
||||
### 3. System Integration
|
||||
|
||||
#### Systemd Service Integration
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Setup systemd service for bootc internals
|
||||
|
||||
# Create service file
|
||||
cat > /etc/systemd/system/bootc-maintenance.service << EOF
|
||||
[Unit]
|
||||
Description=Bootc Maintenance Service
|
||||
After=multi-user.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/bin/bootc-maintenance.sh
|
||||
User=root
|
||||
Group=root
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# Create timer file
|
||||
cat > /etc/systemd/system/bootc-maintenance.timer << EOF
|
||||
[Unit]
|
||||
Description=Bootc Maintenance Timer
|
||||
Requires=bootc-maintenance.service
|
||||
|
||||
[Timer]
|
||||
OnCalendar=daily
|
||||
Persistent=true
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
EOF
|
||||
|
||||
# Enable and start timer
|
||||
systemctl daemon-reload
|
||||
systemctl enable bootc-maintenance.timer
|
||||
systemctl start bootc-maintenance.timer
|
||||
|
||||
# Check timer status
|
||||
systemctl status bootc-maintenance.timer
|
||||
```
|
||||
|
||||
#### Monitoring Integration
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Setup monitoring for bootc internals
|
||||
|
||||
# Create monitoring script
|
||||
cat > /usr/local/bin/bootc-monitor.sh << 'EOF'
|
||||
#!/bin/bash
|
||||
|
||||
# Check system health
|
||||
HEALTH_STATUS=$(bootc internals fsck 2>&1 | grep -c "✗")
|
||||
if [ $HEALTH_STATUS -gt 0 ]; then
|
||||
echo "WARNING: Filesystem consistency issues detected"
|
||||
# Send alert to monitoring system
|
||||
curl -X POST "https://monitoring.example.com/alerts" \
|
||||
-d '{"service": "bootc", "status": "warning", "message": "Filesystem consistency issues"}'
|
||||
fi
|
||||
|
||||
# Check storage usage
|
||||
STORAGE_USAGE=$(df /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//')
|
||||
if [ $STORAGE_USAGE -gt 80 ]; then
|
||||
echo "WARNING: Storage usage is high: ${STORAGE_USAGE}%"
|
||||
# Run cleanup
|
||||
bootc internals cleanup
|
||||
fi
|
||||
|
||||
# Check deployment status
|
||||
DEPLOYMENT_STATUS=$(bootc status --format json | jq -r '.status.booted.state')
|
||||
if [ "$DEPLOYMENT_STATUS" != "active" ]; then
|
||||
echo "WARNING: Deployment status is not active: $DEPLOYMENT_STATUS"
|
||||
fi
|
||||
EOF
|
||||
|
||||
chmod +x /usr/local/bin/bootc-monitor.sh
|
||||
|
||||
# Add to crontab
|
||||
echo "*/5 * * * * /usr/local/bin/bootc-monitor.sh" | crontab -
|
||||
```
|
||||
|
||||
### 4. Debugging and Diagnostics
|
||||
|
||||
#### System Diagnostics
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Comprehensive system diagnostics
|
||||
|
||||
echo "=== Bootc System Diagnostics ==="
|
||||
echo "Date: $(date)"
|
||||
echo "Hostname: $(hostname)"
|
||||
echo "Uptime: $(uptime)"
|
||||
echo
|
||||
|
||||
echo "=== System Status ==="
|
||||
bootc status --format json | jq '.'
|
||||
echo
|
||||
|
||||
echo "=== Filesystem Check ==="
|
||||
bootc internals fsck
|
||||
echo
|
||||
|
||||
echo "=== Storage Usage ==="
|
||||
df -h /var/lib/bootc
|
||||
echo
|
||||
|
||||
echo "=== Memory Usage ==="
|
||||
free -h
|
||||
echo
|
||||
|
||||
echo "=== Process Information ==="
|
||||
ps aux | grep bootc
|
||||
echo
|
||||
|
||||
echo "=== Systemd Services ==="
|
||||
systemctl status bootc-* --no-pager
|
||||
echo
|
||||
|
||||
echo "=== Journal Logs ==="
|
||||
journalctl -u bootc-* --since "1 hour ago" --no-pager
|
||||
echo
|
||||
|
||||
echo "=== OSTree Status ==="
|
||||
ostree admin status
|
||||
echo
|
||||
|
||||
echo "=== Composefs Status ==="
|
||||
bootc internals cfs status
|
||||
echo
|
||||
|
||||
echo "=== Diagnostics Complete ==="
|
||||
```
|
||||
|
||||
#### Performance Analysis
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Performance analysis script
|
||||
|
||||
echo "=== Bootc Performance Analysis ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
echo "=== Command Execution Times ==="
|
||||
time bootc status
|
||||
time bootc internals fsck
|
||||
time bootc internals cleanup
|
||||
echo
|
||||
|
||||
echo "=== Resource Usage ==="
|
||||
echo "Memory usage:"
|
||||
ps aux | grep bootc | awk '{sum+=$6} END {print sum/1024 " MB"}'
|
||||
|
||||
echo "CPU usage:"
|
||||
top -bn1 | grep bootc | awk '{print $9}'
|
||||
|
||||
echo "Disk I/O:"
|
||||
iotop -bn1 | grep bootc
|
||||
echo
|
||||
|
||||
echo "=== System Load ==="
|
||||
uptime
|
||||
echo
|
||||
|
||||
echo "=== Performance Analysis Complete ==="
|
||||
```
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### 1. Common Error Scenarios
|
||||
|
||||
#### Permission Denied Errors
|
||||
|
||||
**Error**: `Permission denied: This command must be executed as the root user`
|
||||
|
||||
**Cause**: Command executed without root privileges
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check current user
|
||||
whoami
|
||||
|
||||
# Switch to root
|
||||
sudo su -
|
||||
|
||||
# Or use sudo
|
||||
sudo bootc internals <command>
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Check if running as root
|
||||
if [ "$EUID" -ne 0 ]; then
|
||||
echo "This script must be run as root"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### Filesystem Consistency Errors
|
||||
|
||||
**Error**: `✗ ostree-repo: Repository integrity check failed`
|
||||
|
||||
**Cause**: OSTree repository corruption
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check repository status
|
||||
ostree admin status
|
||||
|
||||
# Verify repository integrity
|
||||
ostree fsck
|
||||
|
||||
# If corruption detected, restore from backup
|
||||
ostree admin deploy --from-commit <backup-commit>
|
||||
|
||||
# Or reinstall if no backup available
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Regular integrity checks
|
||||
bootc internals fsck
|
||||
|
||||
# Backup important deployments
|
||||
ostree admin pin <deployment-id>
|
||||
```
|
||||
|
||||
#### Storage Space Errors
|
||||
|
||||
**Error**: `No space left on device`
|
||||
|
||||
**Cause**: Insufficient storage space
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check storage usage
|
||||
df -h /var/lib/bootc
|
||||
|
||||
# Run cleanup
|
||||
bootc internals cleanup
|
||||
|
||||
# Remove old deployments
|
||||
ostree admin cleanup
|
||||
|
||||
# Check for large files
|
||||
du -sh /var/lib/bootc/* | sort -hr
|
||||
|
||||
# Remove unnecessary files
|
||||
rm -rf /var/lib/bootc/tmp/*
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Monitor storage usage
|
||||
df -h /var/lib/bootc | awk 'NR==2 {print $5}' | sed 's/%//'
|
||||
|
||||
# Set up alerts
|
||||
if [ $STORAGE_USAGE -gt 80 ]; then
|
||||
echo "WARNING: Storage usage is high"
|
||||
bootc internals cleanup
|
||||
fi
|
||||
```
|
||||
|
||||
#### Systemd Generator Errors
|
||||
|
||||
**Error**: `Failed to generate systemd unit`
|
||||
|
||||
**Cause**: Systemd generator failure
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check systemd status
|
||||
systemctl status bootc-systemd-generator
|
||||
|
||||
# Check generator logs
|
||||
journalctl -u bootc-systemd-generator
|
||||
|
||||
# Manually run generator
|
||||
bootc internals systemd-generator /run/systemd/system
|
||||
|
||||
# Reload systemd
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Regular generator testing
|
||||
bootc internals systemd-generator /tmp/test-units
|
||||
|
||||
# Check systemd configuration
|
||||
systemd-analyze verify /etc/systemd/system/bootc-*
|
||||
```
|
||||
|
||||
### 2. Debugging Techniques
|
||||
|
||||
#### Enable Debug Logging
|
||||
|
||||
```bash
|
||||
# Set debug log level
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Run command with debug output
|
||||
bootc internals fsck
|
||||
|
||||
# Check debug logs
|
||||
journalctl -u bootc-* --since "1 hour ago" | grep DEBUG
|
||||
```
|
||||
|
||||
#### Verbose Output
|
||||
|
||||
```bash
|
||||
# Enable verbose output
|
||||
bootc internals fsck --verbose
|
||||
|
||||
# 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
|
||||
ostree --version
|
||||
bootc --version
|
||||
|
||||
# Check system configuration
|
||||
cat /etc/os-release
|
||||
cat /proc/version
|
||||
cat /proc/cpuinfo | head -20
|
||||
```
|
||||
|
||||
#### Network Diagnostics
|
||||
|
||||
```bash
|
||||
# Check network connectivity
|
||||
ping -c 3 registry.example.com
|
||||
|
||||
# Check DNS resolution
|
||||
nslookup registry.example.com
|
||||
|
||||
# Check firewall rules
|
||||
iptables -L
|
||||
firewall-cmd --list-all
|
||||
|
||||
# Check proxy settings
|
||||
echo $HTTP_PROXY
|
||||
echo $HTTPS_PROXY
|
||||
```
|
||||
|
||||
### 3. Recovery Procedures
|
||||
|
||||
#### System Recovery
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# System recovery script
|
||||
|
||||
echo "=== Bootc System Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system status
|
||||
echo "Checking system status..."
|
||||
bootc status
|
||||
|
||||
# Check filesystem integrity
|
||||
echo "Checking filesystem integrity..."
|
||||
bootc internals fsck
|
||||
|
||||
# If errors found, attempt repair
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Filesystem errors detected, attempting repair..."
|
||||
|
||||
# Try to repair OSTree repository
|
||||
ostree fsck --repair
|
||||
|
||||
# If repair fails, restore from backup
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Repair failed, restoring from backup..."
|
||||
ostree admin deploy --from-commit <backup-commit>
|
||||
fi
|
||||
fi
|
||||
|
||||
# Clean up system
|
||||
echo "Cleaning up system..."
|
||||
bootc internals cleanup
|
||||
|
||||
# Verify system is working
|
||||
echo "Verifying system is working..."
|
||||
bootc status
|
||||
bootc internals fsck
|
||||
|
||||
echo "Recovery complete"
|
||||
```
|
||||
|
||||
#### Data Recovery
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Data recovery script
|
||||
|
||||
echo "=== Bootc Data Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check for available backups
|
||||
echo "Checking for available backups..."
|
||||
ls -la /var/lib/bootc/backups/
|
||||
|
||||
# List available deployments
|
||||
echo "Available deployments:"
|
||||
ostree admin status
|
||||
|
||||
# Check deployment history
|
||||
echo "Deployment history:"
|
||||
ostree log <deployment-id>
|
||||
|
||||
# Attempt to recover specific deployment
|
||||
echo "Attempting to recover deployment..."
|
||||
ostree admin deploy <deployment-id>
|
||||
|
||||
# Verify recovery
|
||||
echo "Verifying recovery..."
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 4. Performance Optimization
|
||||
|
||||
#### System Optimization
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# System optimization script
|
||||
|
||||
echo "=== Bootc System Optimization ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Optimize OSTree repository
|
||||
echo "Optimizing OSTree repository..."
|
||||
ostree admin cleanup
|
||||
|
||||
# Optimize composefs repository
|
||||
echo "Optimizing composefs repository..."
|
||||
bootc internals cfs optimize
|
||||
|
||||
# Clean up temporary files
|
||||
echo "Cleaning up temporary files..."
|
||||
bootc internals cleanup
|
||||
|
||||
# Optimize systemd services
|
||||
echo "Optimizing systemd services..."
|
||||
systemctl daemon-reload
|
||||
systemctl restart bootc-*
|
||||
|
||||
# Check system performance
|
||||
echo "Checking system performance..."
|
||||
bootc internals fsck
|
||||
df -h /var/lib/bootc
|
||||
free -h
|
||||
```
|
||||
|
||||
#### Storage Optimization
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Storage optimization script
|
||||
|
||||
echo "=== Bootc Storage Optimization ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check storage usage
|
||||
echo "Current storage usage:"
|
||||
df -h /var/lib/bootc
|
||||
|
||||
# Remove old deployments
|
||||
echo "Removing old deployments..."
|
||||
ostree admin cleanup --keep=3
|
||||
|
||||
# Remove unused images
|
||||
echo "Removing unused images..."
|
||||
bootc image prune
|
||||
|
||||
# Compress repository
|
||||
echo "Compressing repository..."
|
||||
ostree admin cleanup --compress
|
||||
|
||||
# Check optimized storage usage
|
||||
echo "Optimized storage usage:"
|
||||
df -h /var/lib/bootc
|
||||
```
|
||||
|
||||
### 5. Monitoring and Alerting
|
||||
|
||||
#### Health Check Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Health check script
|
||||
|
||||
HEALTH_STATUS=0
|
||||
|
||||
echo "=== Bootc Health Check ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system status
|
||||
echo "Checking system status..."
|
||||
if ! bootc status > /dev/null 2>&1; then
|
||||
echo "ERROR: System status check failed"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Check filesystem integrity
|
||||
echo "Checking filesystem integrity..."
|
||||
if ! bootc internals fsck > /dev/null 2>&1; then
|
||||
echo "ERROR: Filesystem integrity check failed"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Check storage usage
|
||||
echo "Checking storage usage..."
|
||||
STORAGE_USAGE=$(df /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//')
|
||||
if [ $STORAGE_USAGE -gt 90 ]; then
|
||||
echo "ERROR: Storage usage is critical: ${STORAGE_USAGE}%"
|
||||
HEALTH_STATUS=1
|
||||
elif [ $STORAGE_USAGE -gt 80 ]; then
|
||||
echo "WARNING: Storage usage is high: ${STORAGE_USAGE}%"
|
||||
fi
|
||||
|
||||
# Check memory usage
|
||||
echo "Checking memory usage..."
|
||||
MEMORY_USAGE=$(free | grep Mem | awk '{printf "%.0f", $3/$2 * 100.0}')
|
||||
if [ $MEMORY_USAGE -gt 90 ]; then
|
||||
echo "ERROR: Memory usage is critical: ${MEMORY_USAGE}%"
|
||||
HEALTH_STATUS=1
|
||||
elif [ $MEMORY_USAGE -gt 80 ]; then
|
||||
echo "WARNING: Memory usage is high: ${MEMORY_USAGE}%"
|
||||
fi
|
||||
|
||||
# Check systemd services
|
||||
echo "Checking systemd services..."
|
||||
if ! systemctl is-active bootc-* > /dev/null 2>&1; then
|
||||
echo "ERROR: Some bootc services are not active"
|
||||
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\",
|
||||
\"severity\": \"$severity\",
|
||||
\"message\": \"$message\",
|
||||
\"timestamp\": \"$(date -Iseconds)\"
|
||||
}"
|
||||
}
|
||||
|
||||
# Check system health
|
||||
if ! /usr/local/bin/bootc-health-check.sh; then
|
||||
send_alert "critical" "Bootc system health check failed"
|
||||
fi
|
||||
|
||||
# Check storage usage
|
||||
STORAGE_USAGE=$(df /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//')
|
||||
if [ $STORAGE_USAGE -gt 90 ]; then
|
||||
send_alert "critical" "Storage usage is critical: ${STORAGE_USAGE}%"
|
||||
elif [ $STORAGE_USAGE -gt 80 ]; then
|
||||
send_alert "warning" "Storage usage is high: ${STORAGE_USAGE}%"
|
||||
fi
|
||||
|
||||
# Check memory usage
|
||||
MEMORY_USAGE=$(free | grep Mem | awk '{printf "%.0f", $3/$2 * 100.0}')
|
||||
if [ $MEMORY_USAGE -gt 90 ]; then
|
||||
send_alert "critical" "Memory usage is critical: ${MEMORY_USAGE}%"
|
||||
elif [ $MEMORY_USAGE -gt 80 ]; then
|
||||
send_alert "warning" "Memory usage is high: ${MEMORY_USAGE}%"
|
||||
fi
|
||||
```
|
||||
|
||||
This comprehensive examples and troubleshooting guide provides practical solutions for common issues and advanced debugging techniques for the bootc internals system.
|
||||
980
internals/bootc-internals-external-commands.md
Normal file
980
internals/bootc-internals-external-commands.md
Normal file
|
|
@ -0,0 +1,980 @@
|
|||
# bootc internals - External Commands Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive reference for all external commands used by `bootc internals` operations. These commands are essential for understanding the dependencies and integration points of the bootc internals system.
|
||||
|
||||
## Core Commands
|
||||
|
||||
### bootc
|
||||
|
||||
**Purpose**: Main bootc command for internals operations
|
||||
**Usage**: `bootc internals <subcommand> [options...]`
|
||||
**Dependencies**: None (core command)
|
||||
|
||||
#### Internals Subcommands
|
||||
- `bootc internals systemd-generator` - Generate systemd units
|
||||
- `bootc internals fixup-etc-fstab` - Fix /etc/fstab
|
||||
- `bootc internals print-json-schema` - Generate JSON schemas
|
||||
- `bootc internals fsverity` - Filesystem verity operations
|
||||
- `bootc internals fsck` - Filesystem consistency check
|
||||
- `bootc internals cleanup` - Perform cleanup operations
|
||||
- `bootc internals relabel` - SELinux relabeling
|
||||
- `bootc internals ostree-ext` - Proxy to ostree-ext CLI
|
||||
- `bootc internals cfs` - Proxy to cfsctl CLI
|
||||
- `bootc internals ostree-container` - Proxy to ostree container CLI
|
||||
- `bootc internals test-composefs` - Test composefs repository
|
||||
- `bootc internals loopback-cleanup-helper` - Loopback device cleanup
|
||||
- `bootc internals allocate-cleanup-loopback` - Test loopback allocation
|
||||
- `bootc internals bootc-install-completion` - Complete installation
|
||||
- `bootc internals reboot` - Initiate reboot
|
||||
- `bootc internals publish-rhsm-facts` - Publish RHSM facts
|
||||
- `bootc internals dump-cli-json` - Dump CLI structure as JSON
|
||||
- `bootc internals dir-diff` - Test directory diff functionality
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Generate systemd units
|
||||
bootc internals systemd-generator /run/systemd/system
|
||||
|
||||
# Fix /etc/fstab
|
||||
bootc internals fixup-etc-fstab
|
||||
|
||||
# Run filesystem check
|
||||
bootc internals fsck
|
||||
|
||||
# Clean up system
|
||||
bootc internals cleanup
|
||||
|
||||
# Test composefs
|
||||
bootc internals test-composefs
|
||||
|
||||
# Reboot system
|
||||
bootc internals reboot
|
||||
```
|
||||
|
||||
## Systemd Commands
|
||||
|
||||
### systemctl
|
||||
|
||||
**Purpose**: Systemd service management
|
||||
**Usage**: `systemctl <subcommand> [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
|
||||
- `systemctl daemon-reload` - Reload systemd configuration
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-systemd-generator
|
||||
|
||||
# Start service
|
||||
systemctl start bootc-systemd-generator
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-systemd-generator
|
||||
|
||||
# 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-systemd-generator
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
## OSTree Commands
|
||||
|
||||
### ostree
|
||||
|
||||
**Purpose**: OSTree repository operations
|
||||
**Usage**: `ostree <subcommand> [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
|
||||
- `ostree admin deploy` - Deploy commits
|
||||
- `ostree admin rollback` - Rollback deployments
|
||||
- `ostree admin cleanup` - Clean up deployments
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show repository status
|
||||
ostree admin status
|
||||
|
||||
# List references
|
||||
ostree refs
|
||||
|
||||
# Show commit details
|
||||
ostree show <commit-hash>
|
||||
|
||||
# List repository contents
|
||||
ostree ls <commit-hash>
|
||||
|
||||
# Show file contents
|
||||
ostree cat <commit-hash> /path/to/file
|
||||
|
||||
# Checkout files
|
||||
ostree checkout <commit-hash> /path/to/destination
|
||||
|
||||
# Deploy commit
|
||||
ostree admin deploy <commit-hash>
|
||||
|
||||
# Rollback deployment
|
||||
ostree admin rollback
|
||||
|
||||
# Clean up deployments
|
||||
ostree admin cleanup
|
||||
```
|
||||
|
||||
### ostree-ext
|
||||
|
||||
**Purpose**: Extended OSTree operations
|
||||
**Usage**: `ostree-ext <subcommand> [options...]`
|
||||
**Dependencies**: ostree-ext package
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Container operations
|
||||
ostree-ext container pull quay.io/myorg/image:latest
|
||||
|
||||
# Repository operations
|
||||
ostree-ext repo create /path/to/repo
|
||||
|
||||
# Image operations
|
||||
ostree-ext image build /path/to/image
|
||||
```
|
||||
|
||||
## Composefs Commands
|
||||
|
||||
### cfsctl
|
||||
|
||||
**Purpose**: Composefs control operations
|
||||
**Usage**: `cfsctl <subcommand> [options...]`
|
||||
**Dependencies**: composefs package
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Create repository
|
||||
cfsctl repo create /path/to/repo
|
||||
|
||||
# Import layer
|
||||
cfsctl oci import-layer <sha256> <name>
|
||||
|
||||
# List layers
|
||||
cfsctl oci ls-layer <name>
|
||||
|
||||
# Create filesystem
|
||||
cfsctl create-fs <name> <output>
|
||||
|
||||
# Write boot entries
|
||||
cfsctl write-boot <name> <output>
|
||||
```
|
||||
|
||||
## Filesystem Commands
|
||||
|
||||
### fsverity
|
||||
|
||||
**Purpose**: Filesystem verity operations
|
||||
**Usage**: `fsverity <subcommand> [options...]`
|
||||
**Dependencies**: fsverity-utils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Measure file digest
|
||||
fsverity measure /path/to/file
|
||||
|
||||
# Enable verity
|
||||
fsverity enable /path/to/file
|
||||
|
||||
# Show verity status
|
||||
fsverity status /path/to/file
|
||||
```
|
||||
|
||||
### mount
|
||||
|
||||
**Purpose**: Filesystem mounting
|
||||
**Usage**: `mount [options...] <device> <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Mount filesystem
|
||||
mount /dev/sda1 /mnt
|
||||
|
||||
# Unmount filesystem
|
||||
umount /mnt
|
||||
|
||||
# Check mount points
|
||||
findmnt
|
||||
|
||||
# Mount with options
|
||||
mount -o ro,noexec /dev/sda1 /mnt
|
||||
```
|
||||
|
||||
### umount
|
||||
|
||||
**Purpose**: Unmount filesystems
|
||||
**Usage**: `umount [options...] <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Unmount filesystem
|
||||
umount /mnt
|
||||
|
||||
# Force unmount
|
||||
umount -f /mnt
|
||||
|
||||
# Lazy unmount
|
||||
umount -l /mnt
|
||||
```
|
||||
|
||||
### losetup
|
||||
|
||||
**Purpose**: Loop device management
|
||||
**Usage**: `losetup [options...]`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Create loop device
|
||||
losetup -f /path/to/image
|
||||
|
||||
# List loop devices
|
||||
losetup -a
|
||||
|
||||
# Detach loop device
|
||||
losetup -d /dev/loop0
|
||||
|
||||
# Show loop device info
|
||||
losetup -l
|
||||
```
|
||||
|
||||
## SELinux Commands
|
||||
|
||||
### setsebool
|
||||
|
||||
**Purpose**: Set SELinux boolean values
|
||||
**Usage**: `setsebool [options...] <boolean> <value>`
|
||||
**Dependencies**: policycoreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Set boolean value
|
||||
setsebool -P httpd_can_network_connect 1
|
||||
|
||||
# List boolean values
|
||||
getsebool -a
|
||||
|
||||
# Show boolean value
|
||||
getsebool httpd_can_network_connect
|
||||
```
|
||||
|
||||
### restorecon
|
||||
|
||||
**Purpose**: Restore SELinux contexts
|
||||
**Usage**: `restorecon [options...] <path>`
|
||||
**Dependencies**: policycoreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Restore context
|
||||
restorecon -R /path/to/directory
|
||||
|
||||
# Restore with verbose output
|
||||
restorecon -v /path/to/file
|
||||
|
||||
# Restore with force
|
||||
restorecon -F /path/to/file
|
||||
```
|
||||
|
||||
### chcon
|
||||
|
||||
**Purpose**: Change SELinux context
|
||||
**Usage**: `chcon [options...] <context> <path>`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Change context
|
||||
chcon -t httpd_exec_t /path/to/file
|
||||
|
||||
# Change context recursively
|
||||
chcon -R -t httpd_exec_t /path/to/directory
|
||||
|
||||
# Change context with reference
|
||||
chcon --reference /path/to/reference /path/to/target
|
||||
```
|
||||
|
||||
## 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...] <url>`
|
||||
**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...] <url>`
|
||||
**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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
### kill
|
||||
|
||||
**Purpose**: Send signals to processes
|
||||
**Usage**: `kill [options...] <pid>`
|
||||
**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
|
||||
```
|
||||
|
||||
### pkill
|
||||
|
||||
**Purpose**: Kill processes by name
|
||||
**Usage**: `pkill [options...] <pattern>`
|
||||
**Dependencies**: procps
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Kill by name
|
||||
pkill process_name
|
||||
|
||||
# Force kill by name
|
||||
pkill -9 process_name
|
||||
|
||||
# Kill by pattern
|
||||
pkill -f "pattern"
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Archive Commands
|
||||
|
||||
### tar
|
||||
|
||||
**Purpose**: Archive operations
|
||||
**Usage**: `tar [options...] <archive> [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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Container Commands
|
||||
|
||||
### podman
|
||||
|
||||
**Purpose**: Container runtime
|
||||
**Usage**: `podman <subcommand> [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 <subcommand> [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 .
|
||||
```
|
||||
|
||||
## 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 <subcommand> [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 <subcommand> [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
|
||||
```
|
||||
|
||||
## 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 <command> [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
|
||||
```
|
||||
|
||||
This comprehensive reference covers all external commands used by the bootc internals system, providing examples and usage patterns for each command.
|
||||
419
internals/bootc-internals-flowchart.md
Normal file
419
internals/bootc-internals-flowchart.md
Normal file
|
|
@ -0,0 +1,419 @@
|
|||
# bootc internals - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc internals` process flow, showing the decision points, operations, and data structures involved in internal system operations.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc internals │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Command Arguments │
|
||||
│ │
|
||||
│ • Parse internals subcommand │
|
||||
│ • Parse command-specific options │
|
||||
│ • Validate arguments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Route to Subcommand │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Subcommand Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Systemd │ │ Filesystem │ │ Proxy │ │
|
||||
│ │ Generator │ │ Operations │ │ Commands │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Generate ││ │ │ Fsck ││ │ │ OstreeExt ││ │
|
||||
│ │ │ Units ││ │ │ Cleanup ││ │ │ Cfs ││ │
|
||||
│ │ │ Fix Fstab ││ │ │ Relabel ││ │ │ OstreeCont ││ │
|
||||
│ │ └─────────────┘│ │ │ Fsverity ││ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ │ └─────────────┘│ └─────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ┌─────────────────┐ │ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Testing │ │ │ System │ │ Development │ │
|
||||
│ │ Commands │ │ │ Operations │ │ Tools │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ TestComp ││ │ │ │ Reboot ││ │ │ PrintSchema ││ │
|
||||
│ │ │ Loopback ││ │ │ │ InstallComp ││ │ │ DumpCliJson ││ │
|
||||
│ │ │ DirDiff ││ │ │ │ RhsmFacts ││ │ │ DirDiff ││ │
|
||||
│ │ └─────────────┘│ │ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ │ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Internal operation completed successfully │
|
||||
│ • Results displayed or logged │
|
||||
│ • System state updated if applicable │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Systemd Generator Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Systemd Generator Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check System State │
|
||||
│ │
|
||||
│ • Check if system is ostree-booted │
|
||||
│ • Verify /etc/fstab exists │
|
||||
│ • Check for existing bootc stamps │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Analyze /etc/fstab │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Fstab Analysis │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ From Anaconda │ │ Not From Anaconda │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Generate ││ │ │ No Action Needed ││ │
|
||||
│ │ │ Fstab Editor││ │ │ ││ │
|
||||
│ │ │ Service ││ │ │ • Return false ││ │
|
||||
│ │ │ ││ │ │ • Exit cleanly ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Generate Systemd Unit │
|
||||
│ │
|
||||
│ • Create bootc-fstab-edit.service │
|
||||
│ • Set up service dependencies │
|
||||
│ • Configure service execution │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Systemd unit generated successfully │
|
||||
│ • Service ready for execution │
|
||||
│ • Fstab will be updated on next boot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Filesystem Consistency Check Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Fsck Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize Storage │
|
||||
│ │
|
||||
│ • Get storage instance │
|
||||
│ • Open OSTree repository │
|
||||
│ • Prepare output stream │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Run Consistency Checks │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Check Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ OSTree │ │ Composefs │ │ Deployment │ │
|
||||
│ │ Repository │ │ Repository │ State │ │
|
||||
│ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Check Repo ││ │ │ Check Repo ││ │ │ Check Depl ││ │
|
||||
│ │ │ Integrity ││ │ │ Integrity ││ │ │ States ││ │
|
||||
│ │ │ Validate ││ │ │ Validate ││ │ │ Validate ││ │
|
||||
│ │ │ Objects ││ │ │ Images ││ │ │ Configs ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Report Results │
|
||||
│ │
|
||||
│ • Display check results │
|
||||
│ • Report any errors found │
|
||||
│ • Provide recommendations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • All checks completed │
|
||||
│ │ • System integrity verified │
|
||||
│ │ • Issues reported if found │
|
||||
│ │ • Recommendations provided │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Cleanup Operations Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Cleanup Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize Storage │
|
||||
│ │
|
||||
│ • Get storage instance │
|
||||
│ • Open OSTree repository │
|
||||
│ • Prepare cleanup operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Identify Cleanup Targets │
|
||||
│ │
|
||||
│ • Find old deployments │
|
||||
│ • Identify unused container images │
|
||||
│ • Locate temporary files │
|
||||
│ • Check for orphaned data │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Perform Cleanup │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Cleanup Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Deployments │ │ Images │ │ Temporary │ │
|
||||
│ │ │ │ │ │ Files │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Remove Old ││ │ │ Remove ││ │ │ Remove ││ │
|
||||
│ │ │ Deployments ││ │ │ Unused ││ │ │ Temp Files ││ │
|
||||
│ │ │ Clean Refs ││ │ │ Images ││ │ │ Clean Cache ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Garbage Collection │
|
||||
│ │
|
||||
│ • Run OSTree garbage collection │
|
||||
│ • Clean up repository objects │
|
||||
│ • Update repository metadata │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Cleanup completed successfully │
|
||||
│ • Storage space freed │
|
||||
│ • System optimized │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Proxy Commands Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Proxy Commands Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Proxy Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Proxy Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ OstreeExt │ │ Cfs │ │ OstreeCont │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Parse Args ││ │ │ Parse Args ││ │ │ Parse Args ││ │
|
||||
│ │ │ Call CLI ││ │ │ Call CLI ││ │ │ Call CLI ││ │
|
||||
│ │ │ Return ││ │ │ Return ││ │ │ Return ││ │
|
||||
│ │ │ Results ││ │ │ Results ││ │ │ Results ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Proxy Command │
|
||||
│ │
|
||||
│ • Forward arguments to target CLI │
|
||||
│ • Execute command with proper context │
|
||||
│ • Return results to caller │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Proxy command executed successfully │
|
||||
│ • Results returned to caller │
|
||||
│ • Target CLI completed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Testing Commands Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Testing Commands Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Test Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Test Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ TestComp │ │ Loopback │ │ DirDiff │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Init Repo ││ │ │ Create Dev ││ │ │ Setup Dirs ││ │
|
||||
│ │ │ Write Test ││ │ │ Test Ops ││ │ │ Run Merge ││ │
|
||||
│ │ │ Verify ││ │ │ Cleanup ││ │ │ Verify ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Test │
|
||||
│ │
|
||||
│ • Run test operations │
|
||||
│ • Verify expected results │
|
||||
│ • Clean up test data │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Test completed successfully │
|
||||
│ • Results verified │
|
||||
│ • System state restored │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ System │ │ Permission │ │ Resource │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Not Root │ │ • Access Denied │ │ • Out of Space │ │
|
||||
│ │ • Not Booted │ │ • Invalid Path │ │ • Memory Error │ │
|
||||
│ │ • Invalid State │ │ • File Not Found│ │ • Device Error │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up any partial state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initial State │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ System Ready │ │
|
||||
│ │ │ │
|
||||
│ │ • All services running │ │
|
||||
│ │ • Storage available │ │
|
||||
│ │ • Permissions correct │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Execute Command │ │
|
||||
│ │ │ │
|
||||
│ │ • Parse arguments │ │
|
||||
│ │ • Validate inputs │ │
|
||||
│ │ • Check prerequisites │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Processing State │ │
|
||||
│ │ │ │
|
||||
│ │ • Command executing │ │
|
||||
│ │ • System state changing │ │
|
||||
│ │ • Resources being used │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Final State │ │
|
||||
│ │ │ │
|
||||
│ │ • Command completed │ │
|
||||
│ │ • System state updated │ │
|
||||
│ │ • Resources cleaned up │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc internals process, showing all decision points, operations, and state transitions involved in internal system operations.
|
||||
313
internals/bootc-internals-quick-reference.md
Normal file
313
internals/bootc-internals-quick-reference.md
Normal file
|
|
@ -0,0 +1,313 @@
|
|||
# bootc internals - Quick Reference
|
||||
|
||||
## Command Summary
|
||||
|
||||
| Command | Purpose | Usage |
|
||||
|---------|---------|-------|
|
||||
| `systemd-generator` | Generate systemd units | `bootc internals systemd-generator <dir>` |
|
||||
| `fixup-etc-fstab` | Fix /etc/fstab | `bootc internals fixup-etc-fstab` |
|
||||
| `print-json-schema` | Generate JSON schemas | `bootc internals print-json-schema --of <type>` |
|
||||
| `fsverity` | Filesystem verity ops | `bootc internals fsverity <subcommand>` |
|
||||
| `fsck` | Filesystem consistency | `bootc internals fsck` |
|
||||
| `cleanup` | System cleanup | `bootc internals cleanup` |
|
||||
| `relabel` | SELinux relabeling | `bootc internals relabel <path>` |
|
||||
| `ostree-ext` | Proxy to ostree-ext | `bootc internals ostree-ext [args...]` |
|
||||
| `cfs` | Proxy to cfsctl | `bootc internals cfs [args...]` |
|
||||
| `ostree-container` | Proxy to ostree container | `bootc internals ostree-container [args...]` |
|
||||
| `test-composefs` | Test composefs repo | `bootc internals test-composefs` |
|
||||
| `loopback-cleanup-helper` | Loopback cleanup | `bootc internals loopback-cleanup-helper --device <dev>` |
|
||||
| `allocate-cleanup-loopback` | Test loopback | `bootc internals allocate-cleanup-loopback --file-path <path>` |
|
||||
| `bootc-install-completion` | Complete installation | `bootc internals bootc-install-completion --sysroot <path> --stateroot <name>` |
|
||||
| `reboot` | Initiate reboot | `bootc internals reboot` |
|
||||
| `publish-rhsm-facts` | Publish RHSM facts | `bootc internals publish-rhsm-facts` |
|
||||
| `dump-cli-json` | Dump CLI JSON | `bootc internals dump-cli-json` |
|
||||
| `dir-diff` | Test directory diff | `bootc internals dir-diff <pristine> <current> <new> [--perform-merge]` |
|
||||
|
||||
## Fsverity Subcommands
|
||||
|
||||
| Subcommand | Purpose | Usage |
|
||||
|------------|---------|-------|
|
||||
| `measure` | Measure file digest | `bootc internals fsverity measure --path <file>` |
|
||||
| `enable` | Enable verity | `bootc internals fsverity enable --path <file>` |
|
||||
|
||||
## Common Options
|
||||
|
||||
| Option | Purpose | Example |
|
||||
|--------|---------|---------|
|
||||
| `--help` | Show help | `bootc internals --help` |
|
||||
| `--verbose` | Verbose output | `bootc internals fsck --verbose` |
|
||||
| `--quiet` | Quiet output | `bootc internals cleanup --quiet` |
|
||||
|
||||
## Quick Commands
|
||||
|
||||
### System Maintenance
|
||||
```bash
|
||||
# Daily maintenance
|
||||
bootc internals fsck && bootc internals cleanup
|
||||
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check storage usage
|
||||
df -h /var/lib/bootc
|
||||
```
|
||||
|
||||
### Development
|
||||
```bash
|
||||
# Test composefs
|
||||
bootc internals test-composefs
|
||||
|
||||
# Test loopback device
|
||||
bootc internals allocate-cleanup-loopback --file-path /tmp/test.img
|
||||
|
||||
# Test directory diff
|
||||
bootc internals dir-diff /tmp/pristine /tmp/current /tmp/new --perform-merge
|
||||
```
|
||||
|
||||
### Debugging
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc internals fsck
|
||||
|
||||
# Check systemd services
|
||||
systemctl status bootc-*
|
||||
|
||||
# Check logs
|
||||
journalctl -u bootc-* --since "1 hour ago"
|
||||
```
|
||||
|
||||
### Systemd Integration
|
||||
```bash
|
||||
# Generate units
|
||||
bootc internals systemd-generator /run/systemd/system
|
||||
|
||||
# Fix fstab
|
||||
bootc internals fixup-etc-fstab
|
||||
|
||||
# Reload systemd
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
### Proxy Commands
|
||||
```bash
|
||||
# OSTree operations
|
||||
bootc internals ostree-ext container pull quay.io/myorg/image:latest
|
||||
|
||||
# Composefs operations
|
||||
bootc internals cfs create-fs myimage /tmp/output
|
||||
|
||||
# Legacy ostree container
|
||||
bootc internals ostree-container pull quay.io/myorg/image:latest
|
||||
```
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Meaning | Solution |
|
||||
|------|---------|----------|
|
||||
| 1 | General error | Check logs for details |
|
||||
| 2 | Permission denied | Run as root |
|
||||
| 3 | Resource error | Check storage/memory |
|
||||
| 4 | Configuration error | Check configuration files |
|
||||
| 5 | System error | Check system status |
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Permission Denied
|
||||
```bash
|
||||
# Check user
|
||||
whoami
|
||||
|
||||
# Run as root
|
||||
sudo bootc internals <command>
|
||||
```
|
||||
|
||||
### Storage Full
|
||||
```bash
|
||||
# Check usage
|
||||
df -h /var/lib/bootc
|
||||
|
||||
# Clean up
|
||||
bootc internals cleanup
|
||||
|
||||
# Remove old deployments
|
||||
ostree admin cleanup
|
||||
```
|
||||
|
||||
### Systemd Issues
|
||||
```bash
|
||||
# Check status
|
||||
systemctl status bootc-*
|
||||
|
||||
# Reload configuration
|
||||
systemctl daemon-reload
|
||||
|
||||
# Restart services
|
||||
systemctl restart bootc-*
|
||||
```
|
||||
|
||||
### Filesystem Errors
|
||||
```bash
|
||||
# Check integrity
|
||||
bootc internals fsck
|
||||
|
||||
# Repair if needed
|
||||
ostree fsck --repair
|
||||
|
||||
# Restore from backup
|
||||
ostree admin deploy --from-commit <backup>
|
||||
```
|
||||
|
||||
## 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` |
|
||||
| Systemd units | Generated units | `/run/systemd/system/` |
|
||||
| OSTree repo | Repository data | `/var/lib/bootc/ostree/` |
|
||||
| Composefs repo | Composefs data | `/var/lib/bootc/composefs/` |
|
||||
|
||||
## 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 Storage
|
||||
```bash
|
||||
# Regular cleanup
|
||||
bootc internals cleanup
|
||||
|
||||
# Compress repository
|
||||
ostree admin cleanup --compress
|
||||
|
||||
# Remove old deployments
|
||||
ostree admin cleanup --keep=3
|
||||
```
|
||||
|
||||
### Optimize Performance
|
||||
```bash
|
||||
# Check system load
|
||||
uptime
|
||||
|
||||
# Check memory usage
|
||||
free -h
|
||||
|
||||
# Check disk I/O
|
||||
iotop
|
||||
```
|
||||
|
||||
### Monitor System
|
||||
```bash
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check filesystem integrity
|
||||
bootc internals fsck
|
||||
|
||||
# Check storage usage
|
||||
df -h /var/lib/bootc
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Root Privileges
|
||||
- All internals commands require root privileges
|
||||
- Use `sudo` or switch to root user
|
||||
- Check current user with `whoami`
|
||||
|
||||
### Input Validation
|
||||
- All paths are validated for security
|
||||
- Path traversal attacks are prevented
|
||||
- Absolute paths are required
|
||||
|
||||
### Resource Limits
|
||||
- Memory usage is limited
|
||||
- CPU usage is monitored
|
||||
- Storage usage is tracked
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Regular Maintenance
|
||||
- Run `fsck` daily
|
||||
- Run `cleanup` weekly
|
||||
- Monitor storage usage
|
||||
- Check system logs
|
||||
|
||||
### Development
|
||||
- Use test environments
|
||||
- Test commands before production
|
||||
- Document custom usage
|
||||
- Monitor system health
|
||||
|
||||
### Production
|
||||
- Set up monitoring
|
||||
- Configure alerts
|
||||
- Regular backups
|
||||
- Document procedures
|
||||
|
||||
## Troubleshooting Steps
|
||||
|
||||
1. **Check system status**
|
||||
```bash
|
||||
bootc status
|
||||
systemctl status bootc-*
|
||||
```
|
||||
|
||||
2. **Check logs**
|
||||
```bash
|
||||
journalctl -u bootc-* --since "1 hour ago"
|
||||
tail -f /var/log/bootc/main.log
|
||||
```
|
||||
|
||||
3. **Check resources**
|
||||
```bash
|
||||
df -h /var/lib/bootc
|
||||
free -h
|
||||
uptime
|
||||
```
|
||||
|
||||
4. **Run diagnostics**
|
||||
```bash
|
||||
bootc internals fsck
|
||||
bootc internals cleanup
|
||||
```
|
||||
|
||||
5. **Check configuration**
|
||||
```bash
|
||||
cat /etc/bootc/config.toml
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
## Quick Scripts
|
||||
|
||||
### Health Check
|
||||
```bash
|
||||
#!/bin/bash
|
||||
bootc status && bootc internals fsck && echo "System healthy"
|
||||
```
|
||||
|
||||
### Maintenance
|
||||
```bash
|
||||
#!/bin/bash
|
||||
bootc internals fsck && bootc internals cleanup && echo "Maintenance complete"
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```bash
|
||||
#!/bin/bash
|
||||
df -h /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//'
|
||||
```
|
||||
|
||||
This quick reference provides essential information for using the bootc internals system effectively.
|
||||
543
internals/bootc-internals-technical-guide.md
Normal file
543
internals/bootc-internals-technical-guide.md
Normal file
|
|
@ -0,0 +1,543 @@
|
|||
# bootc internals - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc internals` is a hidden command that provides internal-only operations for system maintenance, debugging, and integration with other tools. These commands are not intended for regular users but are essential for system administrators, developers, and automated tooling.
|
||||
|
||||
## Purpose
|
||||
|
||||
The internals commands serve several critical functions:
|
||||
|
||||
1. **System Maintenance**: Low-level system operations and cleanup
|
||||
2. **Integration**: Proxy frontends for other tools and services
|
||||
3. **Debugging**: Testing and diagnostic capabilities
|
||||
4. **Development**: Internal tooling and schema generation
|
||||
5. **Systemd Integration**: Generator and service management
|
||||
|
||||
## Command Structure
|
||||
|
||||
```rust
|
||||
pub(crate) enum InternalsOpts {
|
||||
SystemdGenerator { normal_dir, early_dir, late_dir },
|
||||
FixupEtcFstab,
|
||||
PrintJsonSchema { of: SchemaType },
|
||||
Fsverity(FsverityOpts),
|
||||
Fsck,
|
||||
Cleanup,
|
||||
Relabel { as_path, path },
|
||||
OstreeExt { args },
|
||||
Cfs { args },
|
||||
OstreeContainer { args },
|
||||
TestComposefs,
|
||||
LoopbackCleanupHelper { device },
|
||||
AllocateCleanupLoopback { file_path },
|
||||
BootcInstallCompletion { sysroot, stateroot },
|
||||
Reboot,
|
||||
PublishRhsmFacts, // Feature-gated
|
||||
DumpCliJson, // Feature-gated
|
||||
DirDiff { pristine_etc, current_etc, new_etc, perform_merge },
|
||||
}
|
||||
```
|
||||
|
||||
## Core Commands
|
||||
|
||||
### 1. Systemd Generator
|
||||
|
||||
**Purpose**: Generate systemd units for bootc integration
|
||||
**Usage**: `bootc internals systemd-generator <normal_dir> [early_dir] [late_dir]`
|
||||
|
||||
```rust
|
||||
InternalsOpts::SystemdGenerator {
|
||||
normal_dir: Utf8PathBuf,
|
||||
early_dir: Option<Utf8PathBuf>,
|
||||
late_dir: Option<Utf8PathBuf>,
|
||||
} => {
|
||||
let unit_dir = &Dir::open_ambient_dir(normal_dir, cap_std::ambient_authority())?;
|
||||
crate::generator::generator(root, unit_dir)
|
||||
}
|
||||
```
|
||||
|
||||
**Functionality**:
|
||||
- Generates systemd units for bootc services
|
||||
- Handles fstab editing for composefs systems
|
||||
- Creates bootc-fstab-edit.service when needed
|
||||
- Integrates with systemd's generator system
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub(crate) fn fstab_generator_impl(root: &Dir, unit_dir: &Dir) -> Result<bool> {
|
||||
// Check if system is ostree-booted
|
||||
if !is_ostree_booted_in(root)? {
|
||||
return Ok(false);
|
||||
}
|
||||
|
||||
// Check /etc/fstab for anaconda stamp
|
||||
if let Some(fd) = root.open_optional("etc/fstab")? {
|
||||
let mut from_anaconda = false;
|
||||
for line in fd.lines() {
|
||||
let line = line?;
|
||||
if line.contains(BOOTC_EDITED_STAMP) {
|
||||
return Ok(false); // Already processed
|
||||
}
|
||||
if line.contains(FSTAB_ANACONDA_STAMP) {
|
||||
from_anaconda = true;
|
||||
}
|
||||
}
|
||||
|
||||
if from_anaconda {
|
||||
generate_fstab_editor(unit_dir)?;
|
||||
return Ok(true);
|
||||
}
|
||||
}
|
||||
Ok(false)
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Filesystem Consistency Check (Fsck)
|
||||
|
||||
**Purpose**: Perform consistency checking on bootc systems
|
||||
**Usage**: `bootc internals fsck`
|
||||
|
||||
```rust
|
||||
InternalsOpts::Fsck => {
|
||||
let sysroot = &get_storage().await?;
|
||||
crate::fsck::fsck(&sysroot, std::io::stdout().lock()).await?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Functionality**:
|
||||
- Validates OSTree repository integrity
|
||||
- Checks composefs repository consistency
|
||||
- Verifies deployment states
|
||||
- Validates system configuration
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub async fn fsck(sysroot: &Storage, mut out: impl Write) -> Result<()> {
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = ostree.repo();
|
||||
|
||||
// Run all registered fsck checks
|
||||
for check in FSCK_CHECKS {
|
||||
match check(sysroot).await {
|
||||
Ok(Ok(())) => writeln!(out, "✓ {}", check.name())?,
|
||||
Ok(Err(e)) => writeln!(out, "✗ {}: {}", check.name(), e)?,
|
||||
Err(e) => writeln!(out, "✗ {}: {}", check.name(), e)?,
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Cleanup Operations
|
||||
|
||||
**Purpose**: Perform cleanup actions on bootc systems
|
||||
**Usage**: `bootc internals cleanup`
|
||||
|
||||
```rust
|
||||
InternalsOpts::Cleanup => {
|
||||
let sysroot = get_storage().await?;
|
||||
crate::deploy::cleanup(&sysroot).await
|
||||
}
|
||||
```
|
||||
|
||||
**Functionality**:
|
||||
- Remove old deployments
|
||||
- Clean up unused container images
|
||||
- Garbage collect OSTree repository
|
||||
- Remove temporary files
|
||||
|
||||
### 4. Filesystem Verity (Fsverity)
|
||||
|
||||
**Purpose**: Manage fsverity integrity verification
|
||||
**Usage**: `bootc internals fsverity <subcommand>`
|
||||
|
||||
```rust
|
||||
pub(crate) enum FsverityOpts {
|
||||
Measure { path: Utf8PathBuf },
|
||||
Enable { path: Utf8PathBuf },
|
||||
}
|
||||
|
||||
// Implementation
|
||||
InternalsOpts::Fsverity(args) => match args {
|
||||
FsverityOpts::Measure { path } => {
|
||||
let fd = std::fs::File::open(&path)?;
|
||||
let digest: fsverity::Sha256HashValue = fsverity::measure_verity(&fd)?;
|
||||
println!("{}", digest.to_hex());
|
||||
Ok(())
|
||||
}
|
||||
FsverityOpts::Enable { path } => {
|
||||
let fd = std::fs::File::open(&path)?;
|
||||
fsverity::enable_verity_raw::<fsverity::Sha256HashValue>(&fd)?;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Subcommands**:
|
||||
- **`measure`**: Calculate fsverity digest of a file
|
||||
- **`enable`**: Enable fsverity verification on a file
|
||||
|
||||
### 5. Proxy Commands
|
||||
|
||||
#### OstreeExt Proxy
|
||||
**Purpose**: Proxy frontend for `ostree-ext` CLI
|
||||
**Usage**: `bootc internals ostree-ext [args...]`
|
||||
|
||||
```rust
|
||||
InternalsOpts::OstreeExt { args } => {
|
||||
ostree_ext::cli::run_from_iter(["ostree-ext".into()].into_iter().chain(args)).await
|
||||
}
|
||||
```
|
||||
|
||||
#### Cfs Proxy
|
||||
**Purpose**: Proxy frontend for `cfsctl` CLI
|
||||
**Usage**: `bootc internals cfs [args...]`
|
||||
|
||||
```rust
|
||||
InternalsOpts::Cfs { args } => {
|
||||
crate::cfsctl::run_from_iter(args.iter()).await
|
||||
}
|
||||
```
|
||||
|
||||
#### OstreeContainer Proxy
|
||||
**Purpose**: Proxy frontend for legacy `ostree container` CLI
|
||||
**Usage**: `bootc internals ostree-container [args...]`
|
||||
|
||||
```rust
|
||||
InternalsOpts::OstreeContainer { args } => {
|
||||
ostree_ext::cli::run_from_iter(
|
||||
["ostree-ext".into(), "container".into()]
|
||||
.into_iter()
|
||||
.chain(args),
|
||||
).await
|
||||
}
|
||||
```
|
||||
|
||||
### 6. System Maintenance
|
||||
|
||||
#### Fixup /etc/fstab
|
||||
**Purpose**: Fix /etc/fstab for composefs systems
|
||||
**Usage**: `bootc internals fixup-etc-fstab`
|
||||
|
||||
```rust
|
||||
InternalsOpts::FixupEtcFstab => {
|
||||
crate::deploy::fixup_etc_fstab(&root)
|
||||
}
|
||||
```
|
||||
|
||||
#### Relabel
|
||||
**Purpose**: SELinux relabeling
|
||||
**Usage**: `bootc internals relabel --as-path <path> <target_path>`
|
||||
|
||||
```rust
|
||||
InternalsOpts::Relabel { as_path, path } => {
|
||||
let root = &Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
|
||||
let path = path.strip_prefix("/")?;
|
||||
let sepolicy = &ostree::SePolicy::new(&gio::File::for_path("/"), gio::Cancellable::NONE)?;
|
||||
crate::lsm::relabel_recurse(root, path, as_path.as_deref(), sepolicy)?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Testing and Development
|
||||
|
||||
#### Test Composefs
|
||||
**Purpose**: Ensure composefs repository is initialized
|
||||
**Usage**: `bootc internals test-composefs`
|
||||
|
||||
```rust
|
||||
InternalsOpts::TestComposefs => {
|
||||
let storage = get_storage().await?;
|
||||
let cfs = storage.get_ensure_composefs()?;
|
||||
let testdata = b"some test data";
|
||||
let testdata_digest = openssl::sha::sha256(testdata);
|
||||
let mut w = SplitStreamWriter::new(&cfs, None, Some(testdata_digest));
|
||||
w.write_inline(testdata);
|
||||
let object = cfs.write_stream(w, Some("testobject"))?.to_hex();
|
||||
// Verify expected digest
|
||||
assert_eq!(object, "expected_digest");
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
#### Loopback Device Management
|
||||
**Purpose**: Manage loopback devices for testing
|
||||
**Usage**:
|
||||
- `bootc internals loopback-cleanup-helper --device <device>`
|
||||
- `bootc internals allocate-cleanup-loopback --file-path <path>`
|
||||
|
||||
```rust
|
||||
InternalsOpts::LoopbackCleanupHelper { device } => {
|
||||
crate::blockdev::run_loopback_cleanup_helper(&device).await
|
||||
}
|
||||
|
||||
InternalsOpts::AllocateCleanupLoopback { file_path: _ } => {
|
||||
let temp_file = tempfile::NamedTempFile::new()?;
|
||||
let temp_path = temp_file.path();
|
||||
|
||||
let loopback = crate::blockdev::LoopbackDevice::new(temp_path)?;
|
||||
println!("Created loopback device: {}", loopback.path());
|
||||
|
||||
// Cleanup
|
||||
drop(loopback);
|
||||
println!("Successfully closed loopback device");
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 8. Installation Completion
|
||||
|
||||
**Purpose**: Complete installation from ostree-ext
|
||||
**Usage**: `bootc internals bootc-install-completion --sysroot <path> --stateroot <name>`
|
||||
|
||||
```rust
|
||||
InternalsOpts::BootcInstallCompletion { sysroot, stateroot } => {
|
||||
let rootfs = &Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
|
||||
crate::install::completion::run_from_ostree(rootfs, &sysroot, &stateroot).await
|
||||
}
|
||||
```
|
||||
|
||||
### 9. System Operations
|
||||
|
||||
#### Reboot
|
||||
**Purpose**: Initiate reboot (for testing)
|
||||
**Usage**: `bootc internals reboot`
|
||||
|
||||
```rust
|
||||
InternalsOpts::Reboot => {
|
||||
crate::reboot::reboot()
|
||||
}
|
||||
```
|
||||
|
||||
#### Print JSON Schema
|
||||
**Purpose**: Generate JSON schemas (for development)
|
||||
**Usage**: `bootc internals print-json-schema --of <type>`
|
||||
|
||||
```rust
|
||||
InternalsOpts::PrintJsonSchema { of } => {
|
||||
let schema = match of {
|
||||
SchemaType::Host => schema_for!(crate::spec::Host),
|
||||
SchemaType::Progress => schema_for!(crate::progress_jsonl::Event),
|
||||
};
|
||||
let mut stdout = std::io::stdout().lock();
|
||||
serde_json::to_writer_pretty(&mut stdout, &schema)?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 10. Feature-Gated Commands
|
||||
|
||||
#### RHSM Facts Publishing
|
||||
**Purpose**: Publish subscription-manager facts
|
||||
**Usage**: `bootc internals publish-rhsm-facts` (requires `rhsm` feature)
|
||||
|
||||
```rust
|
||||
#[cfg(feature = "rhsm")]
|
||||
InternalsOpts::PublishRhsmFacts => {
|
||||
crate::rhsm::publish_facts(&root).await
|
||||
}
|
||||
```
|
||||
|
||||
#### CLI JSON Dump
|
||||
**Purpose**: Dump CLI structure as JSON
|
||||
**Usage**: `bootc internals dump-cli-json` (requires `docgen` feature)
|
||||
|
||||
```rust
|
||||
#[cfg(feature = "docgen")]
|
||||
InternalsOpts::DumpCliJson => {
|
||||
use clap::CommandFactory;
|
||||
let cmd = Opt::command();
|
||||
let json = crate::cli_json::dump_cli_json(&cmd)?;
|
||||
println!("{}", json);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 11. Directory Diff Testing
|
||||
|
||||
**Purpose**: Test etc-diff/etc-merge functionality
|
||||
**Usage**: `bootc internals dir-diff <pristine_etc> <current_etc> <new_etc> [--perform-merge]`
|
||||
|
||||
```rust
|
||||
InternalsOpts::DirDiff {
|
||||
pristine_etc,
|
||||
current_etc,
|
||||
new_etc,
|
||||
perform_merge,
|
||||
} => {
|
||||
// Test 3-way merge functionality
|
||||
let pristine_dir = Dir::open_ambient_dir(&pristine_etc, cap_std::ambient_authority())?;
|
||||
let current_dir = Dir::open_ambient_dir(¤t_etc, cap_std::ambient_authority())?;
|
||||
let new_dir = Dir::open_ambient_dir(&new_etc, cap_std::ambient_authority())?;
|
||||
|
||||
let (pristine_files, current_files, new_files) =
|
||||
traverse_etc(&pristine_dir, ¤t_dir, &new_dir)?;
|
||||
|
||||
if perform_merge {
|
||||
let diff = compute_diff(&pristine_files, ¤t_files)?;
|
||||
merge(¤t_dir, ¤t_files, &new_dir, &new_files, diff)?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### 1. Command Routing
|
||||
|
||||
The internals commands are routed through the main CLI dispatcher:
|
||||
|
||||
```rust
|
||||
match opt {
|
||||
Opt::Internals(opts) => match opts {
|
||||
InternalsOpts::SystemdGenerator { ... } => { ... }
|
||||
InternalsOpts::Fsck => { ... }
|
||||
InternalsOpts::Cleanup => { ... }
|
||||
// ... other commands
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Error Handling
|
||||
|
||||
All internals commands use consistent error handling:
|
||||
|
||||
```rust
|
||||
#[context("Operation name")]
|
||||
pub(crate) fn operation() -> Result<()> {
|
||||
// Implementation with proper error context
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Integration Points
|
||||
|
||||
- **Systemd**: Generator integration for service management
|
||||
- **OSTree**: Direct OSTree operations and repository management
|
||||
- **Composefs**: Composefs repository operations
|
||||
- **SELinux**: Security labeling and policy enforcement
|
||||
- **Filesystem**: Low-level filesystem operations
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Privilege Requirements
|
||||
|
||||
Most internals commands require root privileges:
|
||||
|
||||
```rust
|
||||
pub(crate) fn require_root(is_container: bool) -> Result<()> {
|
||||
ensure!(
|
||||
rustix::process::getuid().is_root(),
|
||||
if is_container {
|
||||
"The user inside the container from which you are running this command must be root"
|
||||
} else {
|
||||
"This command must be executed as the root user"
|
||||
}
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Hidden Commands
|
||||
|
||||
All internals commands are hidden from help output:
|
||||
|
||||
```rust
|
||||
#[clap(subcommand)]
|
||||
#[clap(hide = true)]
|
||||
Internals(InternalsOpts),
|
||||
```
|
||||
|
||||
### 3. Internal Use Only
|
||||
|
||||
Commands are marked as internal-only and not intended for regular users.
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### 1. Systemd Generator
|
||||
|
||||
- **Fast**: Minimal overhead during boot
|
||||
- **Conditional**: Only runs when needed
|
||||
- **Efficient**: Direct filesystem operations
|
||||
|
||||
### 2. Fsck Operations
|
||||
|
||||
- **Comprehensive**: Checks all system components
|
||||
- **Parallel**: Can run multiple checks concurrently
|
||||
- **Detailed**: Provides specific error information
|
||||
|
||||
### 3. Cleanup Operations
|
||||
|
||||
- **Safe**: Only removes confirmed unused data
|
||||
- **Efficient**: Batch operations where possible
|
||||
- **Atomic**: Operations are atomic where possible
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### Generator Not Running
|
||||
```bash
|
||||
# Check systemd generator status
|
||||
systemctl status bootc-systemd-generator
|
||||
|
||||
# Check generator logs
|
||||
journalctl -u bootc-systemd-generator
|
||||
```
|
||||
|
||||
#### Fsck Failures
|
||||
```bash
|
||||
# Run fsck manually
|
||||
bootc internals fsck
|
||||
|
||||
# Check specific components
|
||||
bootc internals fsck --component ostree
|
||||
```
|
||||
|
||||
#### Cleanup Issues
|
||||
```bash
|
||||
# Run cleanup manually
|
||||
bootc internals cleanup
|
||||
|
||||
# Check storage usage
|
||||
df -h /sysroot
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc internals <command>
|
||||
|
||||
# Check system state
|
||||
bootc status
|
||||
|
||||
# Verify system integrity
|
||||
bootc internals fsck
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Usage Guidelines
|
||||
|
||||
- **Internal Only**: Don't use in production scripts
|
||||
- **Root Required**: Always run as root
|
||||
- **Testing**: Use in test environments first
|
||||
- **Documentation**: Document any custom usage
|
||||
|
||||
### 2. Integration Patterns
|
||||
|
||||
- **Systemd**: Use generators for service integration
|
||||
- **Monitoring**: Use fsck for health checks
|
||||
- **Maintenance**: Use cleanup for storage management
|
||||
- **Development**: Use test commands for validation
|
||||
|
||||
### 3. Error Handling
|
||||
|
||||
- **Logging**: Always check logs for errors
|
||||
- **Recovery**: Have recovery procedures ready
|
||||
- **Testing**: Test commands before production use
|
||||
- **Monitoring**: Monitor system health after operations
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc internals system's architecture, implementation, and usage patterns.
|
||||
27
intro.md
Normal file
27
intro.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
# bootc for Debian
|
||||
|
||||
Transactional, in-place operating system updates using OCI/Docker container images. bootc is the key component in a broader mission of bootable containers for Debian systems.
|
||||
|
||||
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 on Debian.
|
||||
|
||||
The container image includes a Linux kernel (in e.g. `/usr/lib/modules`), which is used to boot. At runtime on a target system, the base userspace is _not_ itself running in a container by default. For example, assuming systemd is in use, systemd acts as pid1 as usual - there's no "outer" process.
|
||||
|
||||
## Status
|
||||
|
||||
The CLI and API for bootc are now considered stable. Every existing Debian system can be upgraded in place seamlessly across any future changes.
|
||||
|
||||
However, the core underlying code uses the ostree project which has been powering stable operating system updates for many years. The stability here generally refers to the surface APIs, not the underlying logic.
|
||||
|
||||
## Debian Integration
|
||||
|
||||
bootc for Debian leverages the existing Debian package management system (`apt`) and integrates with Debian's traditional update mechanisms while providing the benefits of container-based OS updates. This allows Debian systems to benefit from:
|
||||
|
||||
- Atomic updates with rollback capability
|
||||
- Container-based OS image management
|
||||
- Simplified system maintenance and deployment
|
||||
- Integration with existing Debian infrastructure
|
||||
|
||||
---
|
||||
|
||||
The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.
|
||||
|
||||
434
lint/bootc-lint-guide.md
Normal file
434
lint/bootc-lint-guide.md
Normal file
|
|
@ -0,0 +1,434 @@
|
|||
# bootc container lint - Comprehensive Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc container lint` is a static analysis tool that performs comprehensive checks on bootc-compatible container images during the build process. It validates that container images meet the requirements for successful bootc installation and runtime operation.
|
||||
|
||||
## Purpose
|
||||
|
||||
The lint tool serves several critical purposes:
|
||||
|
||||
1. **Build-time Validation**: Catch issues early in the container build process
|
||||
2. **Compatibility Assurance**: Ensure images work correctly with bootc installation
|
||||
3. **Best Practice Enforcement**: Promote proper container image construction
|
||||
4. **Runtime Prevention**: Avoid installation failures and runtime issues
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc container lint [OPTIONS...]
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Lint current container image
|
||||
bootc container lint
|
||||
|
||||
# Lint specific rootfs
|
||||
bootc container lint --rootfs /path/to/rootfs
|
||||
|
||||
# List all available lints
|
||||
bootc container lint --list
|
||||
|
||||
# Skip specific lints
|
||||
bootc container lint --skip var-log --skip buildah-injected
|
||||
|
||||
# Make warnings fatal
|
||||
bootc container lint --fatal-warnings
|
||||
|
||||
# Show full output (no truncation)
|
||||
bootc container lint --no-truncate
|
||||
```
|
||||
|
||||
## Lint Categories
|
||||
|
||||
### 1. Fatal Lints
|
||||
|
||||
These lints **must** pass for the container to be installable. Failure will prevent bootc installation.
|
||||
|
||||
#### var-run
|
||||
**Purpose**: Ensures `/var/run` is a symlink to `/run`
|
||||
**Check**: Verifies `/var/run` is not a physical directory
|
||||
**Rationale**: `/var/run` should always be a symlink to `/run` for proper systemd operation
|
||||
|
||||
```bash
|
||||
# This will fail:
|
||||
mkdir -p /var/run
|
||||
|
||||
# This will pass:
|
||||
ln -sf /run /var/run
|
||||
```
|
||||
|
||||
#### etc-usretc
|
||||
**Purpose**: Prevents both `/etc` and `/usr/etc` from existing
|
||||
**Check**: Ensures only `/etc` exists in container images
|
||||
**Rationale**: Having both causes undefined behavior; `/usr/etc` is a bootc implementation detail
|
||||
|
||||
```bash
|
||||
# This will fail:
|
||||
mkdir -p /etc /usr/etc
|
||||
|
||||
# This will pass:
|
||||
mkdir -p /etc
|
||||
# OR
|
||||
mkdir -p /usr/etc
|
||||
```
|
||||
|
||||
#### bootc-kargs
|
||||
**Purpose**: Validates kernel argument configuration files
|
||||
**Check**: Parses `/usr/lib/bootc/kargs.d/*.toml` files for syntax errors
|
||||
**Rationale**: Invalid kernel arguments will cause boot failures
|
||||
|
||||
```bash
|
||||
# Valid kargs.d file:
|
||||
echo '[kargs]
|
||||
append = ["console=ttyS0", "quiet"]' > /usr/lib/bootc/kargs.d/99-console.toml
|
||||
```
|
||||
|
||||
#### kernel
|
||||
**Purpose**: Ensures exactly one kernel is present
|
||||
**Check**: Validates only one `/usr/lib/modules/$kver` directory exists
|
||||
**Rationale**: Multiple kernels cause ambiguity during boot
|
||||
|
||||
```bash
|
||||
# This will fail:
|
||||
mkdir -p /usr/lib/modules/5.4.0 /usr/lib/modules/6.1.0
|
||||
|
||||
# This will pass:
|
||||
mkdir -p /usr/lib/modules/6.1.0
|
||||
```
|
||||
|
||||
#### utf8
|
||||
**Purpose**: Ensures all filenames and symlink targets are UTF-8
|
||||
**Check**: Recursively validates filesystem entries
|
||||
**Rationale**: Non-UTF-8 names cause ostree backend failures
|
||||
|
||||
```bash
|
||||
# This will fail:
|
||||
touch "file\xffname"
|
||||
|
||||
# This will pass:
|
||||
touch "filename"
|
||||
```
|
||||
|
||||
#### api-base-directories
|
||||
**Purpose**: Verifies required API directories exist
|
||||
**Check**: Ensures `/dev`, `/proc`, `/sys`, `/run`, `/tmp`, `/var` exist as directories
|
||||
**Rationale**: These are required by systemd and Linux standards
|
||||
|
||||
```bash
|
||||
# Required directories:
|
||||
mkdir -p /dev /proc /sys /run /tmp /var
|
||||
```
|
||||
|
||||
#### baseimage-root
|
||||
**Purpose**: Validates bootc-specific root filesystem structure
|
||||
**Check**: Ensures `/sysroot` exists and `/ostree` symlinks to `sysroot/ostree`
|
||||
**Rationale**: Required for proper bootc operation
|
||||
|
||||
```bash
|
||||
# Required structure:
|
||||
mkdir -p /sysroot/ostree
|
||||
ln -sf sysroot/ostree /ostree
|
||||
```
|
||||
|
||||
### 2. Warning Lints
|
||||
|
||||
These lints indicate potential issues but don't prevent installation.
|
||||
|
||||
#### buildah-injected
|
||||
**Purpose**: Detects empty files injected by container build systems
|
||||
**Check**: Looks for empty `/etc/hostname` or `/etc/resolv.conf` files
|
||||
**Rationale**: These files should contain actual content, not be empty placeholders
|
||||
|
||||
```bash
|
||||
# This will warn:
|
||||
touch /etc/hostname
|
||||
|
||||
# This will pass:
|
||||
echo "myhostname" > /etc/hostname
|
||||
```
|
||||
|
||||
#### baseimage-composefs
|
||||
**Purpose**: Recommends enabling composefs for ostree
|
||||
**Check**: Validates composefs configuration in `/usr/lib/ostree/prepare-root.conf`
|
||||
**Rationale**: Composefs improves performance and security
|
||||
|
||||
```bash
|
||||
# Enable composefs:
|
||||
echo '[composefs]
|
||||
enabled = true' > /usr/lib/ostree/prepare-root.conf
|
||||
```
|
||||
|
||||
#### var-log
|
||||
**Purpose**: Warns about non-empty log files in `/var/log`
|
||||
**Check**: Identifies regular files with content in `/var/log`
|
||||
**Rationale**: Log files should be generated at runtime, not shipped in images
|
||||
|
||||
```bash
|
||||
# This will warn:
|
||||
echo "log content" > /var/log/app.log
|
||||
|
||||
# This will pass:
|
||||
mkdir -p /var/log
|
||||
# OR
|
||||
ln -sf /dev/null /var/log/app.log
|
||||
```
|
||||
|
||||
#### var-tmpfiles
|
||||
**Purpose**: Checks for missing systemd tmpfiles.d entries
|
||||
**Check**: Validates `/var` content has corresponding tmpfiles.d configuration
|
||||
**Rationale**: Ensures proper initialization across upgrades
|
||||
|
||||
```bash
|
||||
# Create tmpfiles.d entry:
|
||||
echo 'd /var/log/app 0755 root root -' > /usr/lib/tmpfiles.d/app.conf
|
||||
```
|
||||
|
||||
#### sysusers
|
||||
**Purpose**: Validates user/group definitions have systemd sysusers.d entries
|
||||
**Check**: Ensures `/etc/passwd` and `/etc/group` entries have corresponding sysusers.d files
|
||||
**Rationale**: Prevents user/group drift across upgrades
|
||||
|
||||
```bash
|
||||
# Create sysusers.d entry:
|
||||
echo 'u app 1000 "Application User"' > /usr/lib/sysusers.d/app.conf
|
||||
```
|
||||
|
||||
#### nonempty-boot
|
||||
**Purpose**: Warns about content in `/boot` directory
|
||||
**Check**: Ensures `/boot` is empty in container images
|
||||
**Rationale**: Kernel content should be in `/usr/lib/modules`, not `/boot`
|
||||
|
||||
```bash
|
||||
# This will warn:
|
||||
echo "content" > /boot/somefile
|
||||
|
||||
# This will pass:
|
||||
mkdir -p /boot
|
||||
# Keep /boot empty
|
||||
```
|
||||
|
||||
## Integration with Container Builds
|
||||
|
||||
### Dockerfile Integration
|
||||
|
||||
```dockerfile
|
||||
FROM debian:forky-slim
|
||||
|
||||
# Install bootc
|
||||
RUN apt update && apt install -y bootc && apt clean
|
||||
|
||||
# ... your container setup ...
|
||||
|
||||
# Lint the container image
|
||||
RUN bootc container lint
|
||||
|
||||
# Continue with build...
|
||||
```
|
||||
|
||||
### Podman Build Integration
|
||||
|
||||
```bash
|
||||
# Build with linting
|
||||
podman build --tag my-bootc-image .
|
||||
|
||||
# Or run lint separately
|
||||
podman run --rm my-bootc-image bootc container lint
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
- name: Lint bootc container
|
||||
run: |
|
||||
podman run --rm ${{ matrix.image }} bootc container lint --fatal-warnings
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Custom Root Filesystem
|
||||
|
||||
```bash
|
||||
# Lint specific rootfs
|
||||
bootc container lint --rootfs /path/to/rootfs
|
||||
```
|
||||
|
||||
### Selective Linting
|
||||
|
||||
```bash
|
||||
# Skip specific lints
|
||||
bootc container lint --skip var-log --skip buildah-injected
|
||||
|
||||
# List available lints
|
||||
bootc container lint --list
|
||||
```
|
||||
|
||||
### Warning Management
|
||||
|
||||
```bash
|
||||
# Make warnings fatal (fail build on warnings)
|
||||
bootc container lint --fatal-warnings
|
||||
|
||||
# Allow warnings but show full output
|
||||
bootc container lint --no-truncate
|
||||
```
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### 1. /var/run Directory Issue
|
||||
|
||||
**Problem**: `/var/run` exists as a directory instead of symlink
|
||||
**Solution**:
|
||||
```bash
|
||||
rm -rf /var/run
|
||||
ln -sf /run /var/run
|
||||
```
|
||||
|
||||
### 2. Both /etc and /usr/etc Exist
|
||||
|
||||
**Problem**: Container has both directories
|
||||
**Solution**:
|
||||
```bash
|
||||
# Choose one approach:
|
||||
# Option 1: Use /etc only
|
||||
rm -rf /usr/etc
|
||||
|
||||
# Option 2: Use /usr/etc only (not recommended)
|
||||
rm -rf /etc
|
||||
```
|
||||
|
||||
### 3. Multiple Kernels
|
||||
|
||||
**Problem**: Multiple kernel versions present
|
||||
**Solution**:
|
||||
```bash
|
||||
# Keep only one kernel
|
||||
rm -rf /usr/lib/modules/5.4.0
|
||||
# Keep /usr/lib/modules/6.1.0
|
||||
```
|
||||
|
||||
### 4. Non-UTF-8 Filenames
|
||||
|
||||
**Problem**: Files with non-UTF-8 names
|
||||
**Solution**:
|
||||
```bash
|
||||
# Find and rename files
|
||||
find / -name "*" -print0 | xargs -0 -I {} sh -c 'echo "Found: {}"'
|
||||
# Rename problematic files
|
||||
```
|
||||
|
||||
### 5. Missing API Directories
|
||||
|
||||
**Problem**: Required directories missing
|
||||
**Solution**:
|
||||
```bash
|
||||
mkdir -p /dev /proc /sys /run /tmp /var
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Container Image Construction
|
||||
|
||||
- Use minimal base images
|
||||
- Install only necessary packages
|
||||
- Clean up package caches
|
||||
- Avoid creating log files
|
||||
- Use symlinks for `/var/run`
|
||||
|
||||
### 2. User and Group Management
|
||||
|
||||
- Use systemd sysusers.d for user/group definitions
|
||||
- Avoid direct `/etc/passwd` modifications
|
||||
- Use `DynamicUser=yes` in systemd services when possible
|
||||
|
||||
### 3. Filesystem Organization
|
||||
|
||||
- Keep `/boot` empty
|
||||
- Use `/usr/lib/modules` for kernel content
|
||||
- Place configuration in `/usr` when possible
|
||||
- Use tmpfiles.d for runtime directory creation
|
||||
|
||||
### 4. Build Process
|
||||
|
||||
- Run lint early in build process
|
||||
- Use `--fatal-warnings` in CI/CD
|
||||
- Fix issues immediately
|
||||
- Test with actual bootc installation
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```bash
|
||||
# Enable debug output
|
||||
RUST_LOG=debug bootc container lint
|
||||
```
|
||||
|
||||
### Verbose Output
|
||||
|
||||
```bash
|
||||
# Show all issues without truncation
|
||||
bootc container lint --no-truncate
|
||||
```
|
||||
|
||||
### Specific Lint Testing
|
||||
|
||||
```bash
|
||||
# Test specific lint
|
||||
bootc container lint --skip $(bootc container lint --list | grep -v var-run | awk '{print $1}' | tr '\n' ' ')
|
||||
```
|
||||
|
||||
## Integration with Other Tools
|
||||
|
||||
### Pre-commit Hooks
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-commit
|
||||
podman run --rm -v $(pwd):/workspace my-bootc-image bootc container lint --rootfs /workspace
|
||||
```
|
||||
|
||||
### Makefile Integration
|
||||
|
||||
```makefile
|
||||
lint:
|
||||
podman run --rm $(IMAGE) bootc container lint --fatal-warnings
|
||||
|
||||
build: lint
|
||||
podman build --tag $(IMAGE) .
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
services:
|
||||
lint:
|
||||
image: my-bootc-image
|
||||
command: bootc container lint --fatal-warnings
|
||||
volumes:
|
||||
- .:/workspace
|
||||
working_dir: /workspace
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- Lint runs are relatively fast
|
||||
- Recursive checks (like UTF-8) may take longer on large filesystems
|
||||
- Use `--skip` to exclude expensive checks during development
|
||||
- Run full lint in CI/CD pipelines
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- Additional security checks
|
||||
- Performance optimization suggestions
|
||||
- Integration with more container runtimes
|
||||
- Enhanced reporting formats
|
||||
- Custom lint rule support
|
||||
|
||||
---
|
||||
|
||||
This comprehensive guide provides everything needed to effectively use `bootc container lint` for validating bootc-compatible container images.
|
||||
578
lint/examples-and-troubleshooting.md
Normal file
578
lint/examples-and-troubleshooting.md
Normal file
|
|
@ -0,0 +1,578 @@
|
|||
# bootc container lint - Examples and Troubleshooting
|
||||
|
||||
## Practical Examples
|
||||
|
||||
### 1. Basic Container Image Linting
|
||||
|
||||
#### Minimal Working Example
|
||||
|
||||
```dockerfile
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
# Install bootc
|
||||
RUN apt update && apt install -y bootc && apt clean
|
||||
|
||||
# Create required API directories
|
||||
RUN mkdir -p /dev /proc /sys /run /tmp /var
|
||||
|
||||
# Create proper /var/run symlink
|
||||
RUN ln -sf /run /var/run
|
||||
|
||||
# Create /sysroot and /ostree structure
|
||||
RUN mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree
|
||||
|
||||
# Create kernel structure
|
||||
RUN mkdir -p /usr/lib/modules/6.1.0 && \
|
||||
echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz
|
||||
|
||||
# Create empty /boot directory
|
||||
RUN mkdir -p /boot
|
||||
|
||||
# Lint the container
|
||||
RUN bootc container lint
|
||||
```
|
||||
|
||||
#### Common Issues and Fixes
|
||||
|
||||
**Issue**: `/var/run` is a directory instead of symlink
|
||||
```bash
|
||||
# Problem
|
||||
mkdir -p /var/run
|
||||
|
||||
# Fix
|
||||
rm -rf /var/run
|
||||
ln -sf /run /var/run
|
||||
```
|
||||
|
||||
**Issue**: Both `/etc` and `/usr/etc` exist
|
||||
```bash
|
||||
# Problem
|
||||
mkdir -p /etc /usr/etc
|
||||
|
||||
# Fix (choose one)
|
||||
rm -rf /usr/etc # Keep /etc
|
||||
# OR
|
||||
rm -rf /etc # Keep /usr/etc (not recommended)
|
||||
```
|
||||
|
||||
**Issue**: Multiple kernels present
|
||||
```bash
|
||||
# Problem
|
||||
mkdir -p /usr/lib/modules/5.4.0 /usr/lib/modules/6.1.0
|
||||
|
||||
# Fix
|
||||
rm -rf /usr/lib/modules/5.4.0 # Keep only one
|
||||
```
|
||||
|
||||
### 2. Advanced Container Configuration
|
||||
|
||||
#### Complete bootc-compatible Image
|
||||
|
||||
```dockerfile
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
# Install bootc and dependencies
|
||||
RUN apt update && \
|
||||
apt install -y bootc ostree systemd && \
|
||||
apt clean && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Create required API directories
|
||||
RUN mkdir -p /dev /proc /sys /run /tmp /var
|
||||
|
||||
# Fix /var/run symlink
|
||||
RUN ln -sf /run /var/run
|
||||
|
||||
# Create bootc-specific structure
|
||||
RUN mkdir -p /sysroot/ostree && \
|
||||
ln -sf sysroot/ostree /ostree
|
||||
|
||||
# Create kernel structure
|
||||
RUN mkdir -p /usr/lib/modules/6.1.0 && \
|
||||
echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz && \
|
||||
echo "initramfs" > /usr/lib/modules/6.1.0/initramfs.img
|
||||
|
||||
# Create empty /boot directory
|
||||
RUN mkdir -p /boot
|
||||
|
||||
# Configure composefs
|
||||
RUN mkdir -p /usr/lib/ostree && \
|
||||
echo '[composefs]\nenabled = true' > /usr/lib/ostree/prepare-root.conf
|
||||
|
||||
# Configure kernel arguments
|
||||
RUN mkdir -p /usr/lib/bootc/kargs.d && \
|
||||
echo '[kargs]\nappend = ["console=ttyS0", "quiet"]' > /usr/lib/bootc/kargs.d/99-console.toml
|
||||
|
||||
# Create systemd sysusers.d entries
|
||||
RUN mkdir -p /usr/lib/sysusers.d && \
|
||||
echo 'u app 1000 "Application User"' > /usr/lib/sysusers.d/app.conf
|
||||
|
||||
# Create tmpfiles.d entries
|
||||
RUN mkdir -p /usr/lib/tmpfiles.d && \
|
||||
echo 'd /var/log/app 0755 app app -' > /usr/lib/tmpfiles.d/app.conf
|
||||
|
||||
# Lint the container
|
||||
RUN bootc container lint --fatal-warnings
|
||||
```
|
||||
|
||||
### 3. CI/CD Integration Examples
|
||||
|
||||
#### GitHub Actions
|
||||
|
||||
```yaml
|
||||
name: Build and Lint bootc Image
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
build-and-lint:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Build container image
|
||||
run: |
|
||||
podman build --tag my-bootc-image .
|
||||
|
||||
- name: Lint container image
|
||||
run: |
|
||||
podman run --rm my-bootc-image bootc container lint --fatal-warnings
|
||||
|
||||
- name: Test installation
|
||||
run: |
|
||||
podman run --rm --privileged my-bootc-image bootc install to-disk /dev/loop0
|
||||
```
|
||||
|
||||
#### GitLab CI
|
||||
|
||||
```yaml
|
||||
stages:
|
||||
- build
|
||||
- lint
|
||||
- test
|
||||
|
||||
build:
|
||||
stage: build
|
||||
script:
|
||||
- podman build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
|
||||
- podman push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
|
||||
|
||||
lint:
|
||||
stage: lint
|
||||
script:
|
||||
- podman run --rm $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA bootc container lint --fatal-warnings
|
||||
|
||||
test:
|
||||
stage: test
|
||||
script:
|
||||
- podman run --rm --privileged $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA bootc install to-disk /dev/loop0
|
||||
```
|
||||
|
||||
#### Jenkins Pipeline
|
||||
|
||||
```groovy
|
||||
pipeline {
|
||||
agent any
|
||||
|
||||
stages {
|
||||
stage('Build') {
|
||||
steps {
|
||||
sh 'podman build --tag my-bootc-image .'
|
||||
}
|
||||
}
|
||||
|
||||
stage('Lint') {
|
||||
steps {
|
||||
sh 'podman run --rm my-bootc-image bootc container lint --fatal-warnings'
|
||||
}
|
||||
}
|
||||
|
||||
stage('Test') {
|
||||
steps {
|
||||
sh 'podman run --rm --privileged my-bootc-image bootc install to-disk /dev/loop0'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Development Workflow Examples
|
||||
|
||||
#### Pre-commit Hook
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-commit
|
||||
|
||||
echo "Running bootc container lint..."
|
||||
|
||||
# Build the image
|
||||
podman build --tag temp-bootc-image . || exit 1
|
||||
|
||||
# Run lint
|
||||
podman run --rm temp-bootc-image bootc container lint --fatal-warnings || {
|
||||
echo "Lint failed. Please fix issues before committing."
|
||||
podman rmi temp-bootc-image
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Clean up
|
||||
podman rmi temp-bootc-image
|
||||
echo "Lint passed!"
|
||||
```
|
||||
|
||||
#### Makefile Integration
|
||||
|
||||
```makefile
|
||||
.PHONY: build lint test clean
|
||||
|
||||
IMAGE_NAME = my-bootc-image
|
||||
IMAGE_TAG = latest
|
||||
|
||||
build:
|
||||
podman build --tag $(IMAGE_NAME):$(IMAGE_TAG) .
|
||||
|
||||
lint: build
|
||||
podman run --rm $(IMAGE_NAME):$(IMAGE_TAG) bootc container lint --fatal-warnings
|
||||
|
||||
test: lint
|
||||
podman run --rm --privileged $(IMAGE_NAME):$(IMAGE_TAG) bootc install to-disk /dev/loop0
|
||||
|
||||
clean:
|
||||
podman rmi $(IMAGE_NAME):$(IMAGE_TAG) || true
|
||||
|
||||
all: test
|
||||
```
|
||||
|
||||
#### Docker Compose
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
build:
|
||||
build: .
|
||||
image: my-bootc-image:latest
|
||||
|
||||
lint:
|
||||
image: my-bootc-image:latest
|
||||
command: bootc container lint --fatal-warnings
|
||||
depends_on:
|
||||
- build
|
||||
|
||||
test:
|
||||
image: my-bootc-image:latest
|
||||
command: bootc install to-disk /dev/loop0
|
||||
privileged: true
|
||||
depends_on:
|
||||
- lint
|
||||
```
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### 1. Common Error Messages
|
||||
|
||||
#### "Failed lint: var-run: Not a symlink: var/run"
|
||||
|
||||
**Problem**: `/var/run` exists as a directory instead of symlink
|
||||
**Solution**:
|
||||
```bash
|
||||
# Remove directory and create symlink
|
||||
rm -rf /var/run
|
||||
ln -sf /run /var/run
|
||||
```
|
||||
|
||||
**Dockerfile Fix**:
|
||||
```dockerfile
|
||||
RUN rm -rf /var/run && ln -sf /run /var/run
|
||||
```
|
||||
|
||||
#### "Failed lint: etc-usretc: Found /usr/etc - this is a bootc implementation detail"
|
||||
|
||||
**Problem**: Both `/etc` and `/usr/etc` exist
|
||||
**Solution**:
|
||||
```bash
|
||||
# Choose one approach
|
||||
rm -rf /usr/etc # Keep /etc (recommended)
|
||||
# OR
|
||||
rm -rf /etc # Keep /usr/etc (not recommended)
|
||||
```
|
||||
|
||||
**Dockerfile Fix**:
|
||||
```dockerfile
|
||||
RUN rm -rf /usr/etc # Keep /etc only
|
||||
```
|
||||
|
||||
#### "Failed lint: kernel: Multiple kernels found"
|
||||
|
||||
**Problem**: Multiple kernel versions present
|
||||
**Solution**:
|
||||
```bash
|
||||
# Keep only one kernel version
|
||||
rm -rf /usr/lib/modules/5.4.0
|
||||
# Keep /usr/lib/modules/6.1.0
|
||||
```
|
||||
|
||||
**Dockerfile Fix**:
|
||||
```dockerfile
|
||||
RUN rm -rf /usr/lib/modules/5.4.0 # Keep only 6.1.0
|
||||
```
|
||||
|
||||
#### "Failed lint: utf8: Found non-utf8 filename"
|
||||
|
||||
**Problem**: Files with non-UTF-8 names
|
||||
**Solution**:
|
||||
```bash
|
||||
# Find and rename problematic files
|
||||
find / -name "*" -print0 | xargs -0 -I {} sh -c 'echo "Checking: {}"'
|
||||
# Rename files with non-UTF-8 names
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```dockerfile
|
||||
# Use UTF-8 locale
|
||||
ENV LANG=C.UTF-8
|
||||
ENV LC_ALL=C.UTF-8
|
||||
```
|
||||
|
||||
#### "Failed lint: api-base-directories: Missing API filesystem base directory"
|
||||
|
||||
**Problem**: Required directories missing
|
||||
**Solution**:
|
||||
```bash
|
||||
# Create all required directories
|
||||
mkdir -p /dev /proc /sys /run /tmp /var
|
||||
```
|
||||
|
||||
**Dockerfile Fix**:
|
||||
```dockerfile
|
||||
RUN mkdir -p /dev /proc /sys /run /tmp /var
|
||||
```
|
||||
|
||||
### 2. Warning Messages
|
||||
|
||||
#### "Lint warning: buildah-injected: /etc/hostname is an empty file"
|
||||
|
||||
**Problem**: Empty files injected by build system
|
||||
**Solution**:
|
||||
```bash
|
||||
# Remove empty files or add content
|
||||
rm /etc/hostname
|
||||
# OR
|
||||
echo "myhostname" > /etc/hostname
|
||||
```
|
||||
|
||||
**Dockerfile Fix**:
|
||||
```dockerfile
|
||||
RUN rm -f /etc/hostname /etc/resolv.conf
|
||||
```
|
||||
|
||||
#### "Lint warning: var-log: Found non-empty logfiles"
|
||||
|
||||
**Problem**: Log files in container image
|
||||
**Solution**:
|
||||
```bash
|
||||
# Remove log files
|
||||
rm -rf /var/log/*
|
||||
# OR create symlinks to /dev/null
|
||||
ln -sf /dev/null /var/log/app.log
|
||||
```
|
||||
|
||||
**Dockerfile Fix**:
|
||||
```dockerfile
|
||||
RUN rm -rf /var/log/* && \
|
||||
mkdir -p /var/log && \
|
||||
ln -sf /dev/null /var/log/app.log
|
||||
```
|
||||
|
||||
#### "Lint warning: nonempty-boot: Found non-empty /boot"
|
||||
|
||||
**Problem**: Content in `/boot` directory
|
||||
**Solution**:
|
||||
```bash
|
||||
# Remove content from /boot
|
||||
rm -rf /boot/*
|
||||
# Keep /boot empty
|
||||
```
|
||||
|
||||
**Dockerfile Fix**:
|
||||
```dockerfile
|
||||
RUN rm -rf /boot/* && mkdir -p /boot
|
||||
```
|
||||
|
||||
### 3. Debugging Techniques
|
||||
|
||||
#### Enable Debug Output
|
||||
|
||||
```bash
|
||||
# Enable detailed logging
|
||||
RUST_LOG=debug bootc container lint
|
||||
|
||||
# Show all issues without truncation
|
||||
bootc container lint --no-truncate
|
||||
|
||||
# List all available lints
|
||||
bootc container lint --list
|
||||
```
|
||||
|
||||
#### Test Specific Lints
|
||||
|
||||
```bash
|
||||
# Test only fatal lints
|
||||
bootc container lint --skip var-log --skip buildah-injected --skip baseimage-composefs --skip var-tmpfiles --skip sysusers --skip nonempty-boot
|
||||
|
||||
# Test only warning lints
|
||||
bootc container lint --skip var-run --skip etc-usretc --skip bootc-kargs --skip kernel --skip utf8 --skip api-base-directories --skip baseimage-root
|
||||
```
|
||||
|
||||
#### Inspect Container Structure
|
||||
|
||||
```bash
|
||||
# Explore container filesystem
|
||||
podman run --rm -it my-image bash
|
||||
|
||||
# Check specific directories
|
||||
ls -la /var/run
|
||||
ls -la /etc /usr/etc
|
||||
ls -la /usr/lib/modules/
|
||||
ls -la /boot
|
||||
```
|
||||
|
||||
### 4. Performance Optimization
|
||||
|
||||
#### Skip Expensive Lints During Development
|
||||
|
||||
```bash
|
||||
# Skip recursive UTF-8 check during development
|
||||
bootc container lint --skip utf8
|
||||
|
||||
# Skip all warning lints
|
||||
bootc container lint --skip var-log --skip buildah-injected --skip baseimage-composefs --skip var-tmpfiles --skip sysusers --skip nonempty-boot
|
||||
```
|
||||
|
||||
#### Use Faster Base Images
|
||||
|
||||
```dockerfile
|
||||
# Use minimal base image
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
# Avoid unnecessary packages
|
||||
RUN apt update && \
|
||||
apt install -y --no-install-recommends bootc && \
|
||||
apt clean && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
```
|
||||
|
||||
### 5. Integration Issues
|
||||
|
||||
#### Container Runtime Compatibility
|
||||
|
||||
**Problem**: Lint fails in different container runtime
|
||||
**Solution**:
|
||||
```bash
|
||||
# Use podman (recommended)
|
||||
podman run --rm my-image bootc container lint
|
||||
|
||||
# Use docker with proper flags
|
||||
docker run --rm my-image bootc container lint
|
||||
```
|
||||
|
||||
#### Build Context Issues
|
||||
|
||||
**Problem**: Lint fails due to build context
|
||||
**Solution**:
|
||||
```dockerfile
|
||||
# Ensure proper working directory
|
||||
WORKDIR /
|
||||
|
||||
# Copy files explicitly
|
||||
COPY . /workspace
|
||||
WORKDIR /workspace
|
||||
```
|
||||
|
||||
#### Permission Issues
|
||||
|
||||
**Problem**: Permission denied errors
|
||||
**Solution**:
|
||||
```bash
|
||||
# Run with proper permissions
|
||||
podman run --rm --user root my-image bootc container lint
|
||||
|
||||
# Or fix permissions in container
|
||||
RUN chmod -R 755 /usr/lib/bootc
|
||||
```
|
||||
|
||||
### 6. Advanced Troubleshooting
|
||||
|
||||
#### Custom Lint Configuration
|
||||
|
||||
```bash
|
||||
# Create custom lint script
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "Running custom lint checks..."
|
||||
|
||||
# Run specific lints
|
||||
bootc container lint --skip utf8 --skip var-log
|
||||
|
||||
# Additional custom checks
|
||||
if [ -f /etc/hostname ]; then
|
||||
echo "Warning: /etc/hostname should not exist in container"
|
||||
fi
|
||||
|
||||
echo "Custom lint checks passed!"
|
||||
```
|
||||
|
||||
#### Lint Result Analysis
|
||||
|
||||
```bash
|
||||
# Capture lint output for analysis
|
||||
bootc container lint --no-truncate > lint-results.txt 2>&1
|
||||
|
||||
# Analyze results
|
||||
grep "Failed lint" lint-results.txt
|
||||
grep "Lint warning" lint-results.txt
|
||||
```
|
||||
|
||||
#### Automated Fixes
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Auto-fix common issues
|
||||
|
||||
echo "Fixing common bootc lint issues..."
|
||||
|
||||
# Fix /var/run
|
||||
if [ -d /var/run ] && [ ! -L /var/run ]; then
|
||||
echo "Fixing /var/run symlink..."
|
||||
rm -rf /var/run
|
||||
ln -sf /run /var/run
|
||||
fi
|
||||
|
||||
# Fix /usr/etc
|
||||
if [ -d /usr/etc ] && [ -d /etc ]; then
|
||||
echo "Removing /usr/etc (keeping /etc)..."
|
||||
rm -rf /usr/etc
|
||||
fi
|
||||
|
||||
# Fix /boot
|
||||
if [ -d /boot ] && [ "$(ls -A /boot)" ]; then
|
||||
echo "Clearing /boot directory..."
|
||||
rm -rf /boot/*
|
||||
fi
|
||||
|
||||
# Fix log files
|
||||
if [ -d /var/log ] && [ "$(ls -A /var/log)" ]; then
|
||||
echo "Clearing log files..."
|
||||
rm -rf /var/log/*
|
||||
fi
|
||||
|
||||
echo "Auto-fix completed!"
|
||||
```
|
||||
|
||||
This comprehensive examples and troubleshooting guide provides practical solutions for common bootc lint issues and integration patterns.
|
||||
243
lint/quick-reference.md
Normal file
243
lint/quick-reference.md
Normal file
|
|
@ -0,0 +1,243 @@
|
|||
# bootc container lint - Quick Reference
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc container lint [OPTIONS...]
|
||||
```
|
||||
|
||||
## Common Options
|
||||
|
||||
| Option | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `--rootfs` | Specify root filesystem path | `--rootfs /path/to/rootfs` |
|
||||
| `--fatal-warnings` | Treat warnings as fatal errors | `--fatal-warnings` |
|
||||
| `--list` | List all available lints | `--list` |
|
||||
| `--skip` | Skip specific lints | `--skip var-log --skip buildah-injected` |
|
||||
| `--no-truncate` | Show full output (no truncation) | `--no-truncate` |
|
||||
|
||||
## Fatal Lints (Must Pass)
|
||||
|
||||
| Lint | Purpose | Fix |
|
||||
|------|---------|-----|
|
||||
| `var-run` | `/var/run` must be symlink to `/run` | `ln -sf /run /var/run` |
|
||||
| `etc-usretc` | Only `/etc` OR `/usr/etc` (not both) | `rm -rf /usr/etc` |
|
||||
| `bootc-kargs` | Valid kernel args in `/usr/lib/bootc/kargs.d/` | Fix TOML syntax |
|
||||
| `kernel` | Exactly one kernel in `/usr/lib/modules/` | `rm -rf /usr/lib/modules/5.4.0` |
|
||||
| `utf8` | All filenames must be UTF-8 | Rename non-UTF-8 files |
|
||||
| `api-base-directories` | Required dirs: `/dev`, `/proc`, `/sys`, `/run`, `/tmp`, `/var` | `mkdir -p /dev /proc /sys /run /tmp /var` |
|
||||
| `baseimage-root` | Required: `/sysroot`, `/ostree -> sysroot/ostree` | `mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree` |
|
||||
|
||||
## Warning Lints (Recommended)
|
||||
|
||||
| Lint | Purpose | Fix |
|
||||
|------|---------|-----|
|
||||
| `buildah-injected` | No empty `/etc/hostname` or `/etc/resolv.conf` | `rm /etc/hostname /etc/resolv.conf` |
|
||||
| `baseimage-composefs` | Enable composefs in ostree | `echo '[composefs]\nenabled = true' > /usr/lib/ostree/prepare-root.conf` |
|
||||
| `var-log` | No log files in `/var/log` | `rm -rf /var/log/*` |
|
||||
| `var-tmpfiles` | `/var` content needs tmpfiles.d entries | Create `/usr/lib/tmpfiles.d/*.conf` |
|
||||
| `sysusers` | Users/groups need sysusers.d entries | Create `/usr/lib/sysusers.d/*.conf` |
|
||||
| `nonempty-boot` | `/boot` should be empty | `rm -rf /boot/*` |
|
||||
|
||||
## Quick Fixes
|
||||
|
||||
### Fix Common Issues
|
||||
|
||||
```bash
|
||||
# Fix /var/run
|
||||
rm -rf /var/run && ln -sf /run /var/run
|
||||
|
||||
# Fix /usr/etc
|
||||
rm -rf /usr/etc
|
||||
|
||||
# Fix /boot
|
||||
rm -rf /boot/* && mkdir -p /boot
|
||||
|
||||
# Fix log files
|
||||
rm -rf /var/log/*
|
||||
|
||||
# Fix empty files
|
||||
rm -f /etc/hostname /etc/resolv.conf
|
||||
```
|
||||
|
||||
### Create Required Structure
|
||||
|
||||
```bash
|
||||
# API directories
|
||||
mkdir -p /dev /proc /sys /run /tmp /var
|
||||
|
||||
# bootc structure
|
||||
mkdir -p /sysroot/ostree
|
||||
ln -sf sysroot/ostree /ostree
|
||||
|
||||
# Kernel structure
|
||||
mkdir -p /usr/lib/modules/6.1.0
|
||||
echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz
|
||||
|
||||
# Empty /boot
|
||||
mkdir -p /boot
|
||||
```
|
||||
|
||||
## Dockerfile Examples
|
||||
|
||||
### Minimal Working Container
|
||||
|
||||
```dockerfile
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
# Install bootc
|
||||
RUN apt update && apt install -y bootc && apt clean
|
||||
|
||||
# Fix common issues
|
||||
RUN rm -rf /var/run && ln -sf /run /var/run
|
||||
RUN rm -rf /usr/etc
|
||||
RUN rm -rf /boot/* && mkdir -p /boot
|
||||
RUN rm -rf /var/log/*
|
||||
|
||||
# Create required structure
|
||||
RUN mkdir -p /dev /proc /sys /run /tmp /var
|
||||
RUN mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree
|
||||
RUN mkdir -p /usr/lib/modules/6.1.0
|
||||
RUN echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz
|
||||
|
||||
# Lint
|
||||
RUN bootc container lint --fatal-warnings
|
||||
```
|
||||
|
||||
### Complete bootc Image
|
||||
|
||||
```dockerfile
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
# Install dependencies
|
||||
RUN apt update && \
|
||||
apt install -y bootc ostree systemd && \
|
||||
apt clean && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Fix common issues
|
||||
RUN rm -rf /var/run && ln -sf /run /var/run
|
||||
RUN rm -rf /usr/etc
|
||||
RUN rm -rf /boot/* && mkdir -p /boot
|
||||
RUN rm -rf /var/log/*
|
||||
|
||||
# Create required structure
|
||||
RUN mkdir -p /dev /proc /sys /run /tmp /var
|
||||
RUN mkdir -p /sysroot/ostree && ln -sf sysroot/ostree /ostree
|
||||
RUN mkdir -p /usr/lib/modules/6.1.0
|
||||
RUN echo "kernel" > /usr/lib/modules/6.1.0/vmlinuz
|
||||
|
||||
# Configure composefs
|
||||
RUN mkdir -p /usr/lib/ostree && \
|
||||
echo '[composefs]\nenabled = true' > /usr/lib/ostree/prepare-root.conf
|
||||
|
||||
# Configure kernel args
|
||||
RUN mkdir -p /usr/lib/bootc/kargs.d && \
|
||||
echo '[kargs]\nappend = ["console=ttyS0", "quiet"]' > /usr/lib/bootc/kargs.d/99-console.toml
|
||||
|
||||
# Lint
|
||||
RUN bootc container lint --fatal-warnings
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
- name: Lint bootc container
|
||||
run: podman run --rm ${{ matrix.image }} bootc container lint --fatal-warnings
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
lint:
|
||||
script:
|
||||
- podman run --rm $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA bootc container lint --fatal-warnings
|
||||
```
|
||||
|
||||
### Jenkins
|
||||
|
||||
```groovy
|
||||
stage('Lint') {
|
||||
steps {
|
||||
sh 'podman run --rm my-image bootc container lint --fatal-warnings'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
# Basic lint
|
||||
bootc container lint
|
||||
|
||||
# Lint with warnings as fatal
|
||||
bootc container lint --fatal-warnings
|
||||
|
||||
# Lint specific rootfs
|
||||
bootc container lint --rootfs /path/to/rootfs
|
||||
|
||||
# Skip specific lints
|
||||
bootc container lint --skip var-log --skip buildah-injected
|
||||
|
||||
# Show all issues
|
||||
bootc container lint --no-truncate
|
||||
|
||||
# List available lints
|
||||
bootc container lint --list
|
||||
|
||||
# Debug mode
|
||||
RUST_LOG=debug bootc container lint
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Errors
|
||||
|
||||
| Error | Cause | Fix |
|
||||
|-------|-------|-----|
|
||||
| `Not a symlink: var/run` | `/var/run` is directory | `ln -sf /run /var/run` |
|
||||
| `Found /usr/etc` | Both `/etc` and `/usr/etc` exist | `rm -rf /usr/etc` |
|
||||
| `Multiple kernels found` | Multiple kernel versions | Keep only one |
|
||||
| `Found non-utf8 filename` | Non-UTF-8 filenames | Rename files |
|
||||
| `Missing API filesystem base directory` | Missing required dirs | `mkdir -p /dev /proc /sys /run /tmp /var` |
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Check container structure
|
||||
podman run --rm -it my-image bash
|
||||
ls -la /var/run
|
||||
ls -la /etc /usr/etc
|
||||
ls -la /usr/lib/modules/
|
||||
ls -la /boot
|
||||
|
||||
# Test specific lints
|
||||
bootc container lint --skip utf8 --skip var-log
|
||||
|
||||
# Show full output
|
||||
bootc container lint --no-truncate
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Run lint early** in build process
|
||||
2. **Use `--fatal-warnings`** in CI/CD
|
||||
3. **Fix issues immediately** when found
|
||||
4. **Test with actual bootc installation**
|
||||
5. **Use minimal base images**
|
||||
6. **Clean up package caches**
|
||||
7. **Avoid creating log files**
|
||||
8. **Use symlinks for `/var/run`**
|
||||
|
||||
## File Locations
|
||||
|
||||
| Purpose | Location |
|
||||
|---------|----------|
|
||||
| Kernel args | `/usr/lib/bootc/kargs.d/*.toml` |
|
||||
| Composefs config | `/usr/lib/ostree/prepare-root.conf` |
|
||||
| Sysusers config | `/usr/lib/sysusers.d/*.conf` |
|
||||
| Tmpfiles config | `/usr/lib/tmpfiles.d/*.conf` |
|
||||
| Kernel files | `/usr/lib/modules/$kver/vmlinuz` |
|
||||
| Initramfs | `/usr/lib/modules/$kver/initramfs.img` |
|
||||
550
lint/technical-reference.md
Normal file
550
lint/technical-reference.md
Normal file
|
|
@ -0,0 +1,550 @@
|
|||
# bootc container lint - Technical Reference
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The bootc lint system is built on a distributed slice architecture using the `linkme` crate, allowing for modular lint registration and execution. The system supports both regular and recursive lints, with configurable execution and output formatting.
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Lint Registration System
|
||||
|
||||
```rust
|
||||
// From lints.rs:86-87
|
||||
#[distributed_slice]
|
||||
pub(crate) static LINTS: [Lint];
|
||||
```
|
||||
|
||||
**Purpose**: Central registry for all lint checks
|
||||
**Implementation**: Uses `linkme` distributed slices for automatic registration
|
||||
**Benefits**: Modular design, easy addition of new lints
|
||||
|
||||
### 2. Lint Types
|
||||
|
||||
#### Fatal Lints
|
||||
```rust
|
||||
// From lints.rs:92-98
|
||||
enum LintType {
|
||||
Fatal, // Must pass for installation
|
||||
Warning, // Recommended but not required
|
||||
}
|
||||
```
|
||||
|
||||
**Fatal Lints**: Prevent bootc installation if they fail
|
||||
**Warning Lints**: Show warnings but allow installation to proceed
|
||||
|
||||
### 3. Root Type Classification
|
||||
|
||||
```rust
|
||||
// From lints.rs:106-111
|
||||
enum RootType {
|
||||
Running, // Running system root
|
||||
Alternative, // Alternative/container root
|
||||
}
|
||||
```
|
||||
|
||||
**Running**: Lints that apply to running systems
|
||||
**Alternative**: Lints that apply to container images
|
||||
|
||||
## Lint Execution Engine
|
||||
|
||||
### 1. Execution Flow
|
||||
|
||||
```rust
|
||||
// From lints.rs:254-364
|
||||
fn lint_inner<'skip>(
|
||||
root: &Dir,
|
||||
root_type: RootType,
|
||||
config: &LintExecutionConfig,
|
||||
skip: impl IntoIterator<Item = &'skip str>,
|
||||
mut output: impl std::io::Write,
|
||||
) -> Result<LintExecutionResult>
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. Filter applicable lints based on root type
|
||||
2. Separate regular and recursive lints
|
||||
3. Execute regular lints
|
||||
4. Execute recursive lints via filesystem walk
|
||||
5. Collect and report results
|
||||
|
||||
### 2. Recursive Lint Execution
|
||||
|
||||
```rust
|
||||
// From lints.rs:295-328
|
||||
root.walk(
|
||||
&WalkConfiguration::default()
|
||||
.noxdev()
|
||||
.path_base(Path::new("/")),
|
||||
|e| -> std::io::Result<_> {
|
||||
// Execute recursive lints on each filesystem entry
|
||||
},
|
||||
)?;
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Filesystem traversal with `noxdev` (no cross-device)
|
||||
- Early termination on first error
|
||||
- Efficient processing of large filesystems
|
||||
|
||||
### 3. Output Formatting
|
||||
|
||||
```rust
|
||||
// From lints.rs:200-235
|
||||
fn format_items<T>(
|
||||
config: &LintExecutionConfig,
|
||||
header: &str,
|
||||
items: impl Iterator<Item = T>,
|
||||
o: &mut String,
|
||||
) -> Result<()>
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Configurable truncation (default: 5 items)
|
||||
- Consistent formatting across lints
|
||||
- Support for custom display implementations
|
||||
|
||||
## Individual Lint Implementations
|
||||
|
||||
### 1. var-run Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:397-410
|
||||
static LINT_VAR_RUN: Lint = Lint::new_fatal(
|
||||
"var-run",
|
||||
"Check for /var/run being a physical directory; this is always a bug.",
|
||||
check_var_run,
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Ensures `/var/run` is a symlink to `/run`
|
||||
**Check**: Validates symlink existence and target
|
||||
**Rationale**: Required for proper systemd operation
|
||||
|
||||
### 2. etc-usretc Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:435-458
|
||||
static LINT_ETC_USRUSETC: Lint = Lint::new_fatal(
|
||||
"etc-usretc",
|
||||
"Verify that only one of /etc or /usr/etc exist...",
|
||||
check_usretc,
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Prevents both `/etc` and `/usr/etc` from existing
|
||||
**Check**: Validates mutual exclusivity
|
||||
**Rationale**: `/usr/etc` is a bootc implementation detail
|
||||
|
||||
### 3. bootc-kargs Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:461-471
|
||||
static LINT_KARGS: Lint = Lint::new_fatal(
|
||||
"bootc-kargs",
|
||||
"Verify syntax of /usr/lib/bootc/kargs.d.",
|
||||
check_parse_kargs,
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Validates kernel argument configuration
|
||||
**Check**: Parses TOML files in `/usr/lib/bootc/kargs.d/`
|
||||
**Integration**: Uses `crate::bootc_kargs::get_kargs_in_root`
|
||||
|
||||
### 4. kernel Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:473-486
|
||||
static LINT_KERNEL: Lint = Lint::new_fatal(
|
||||
"kernel",
|
||||
"Check for multiple kernels...",
|
||||
check_kernel,
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Ensures exactly one kernel is present
|
||||
**Check**: Validates `/usr/lib/modules/$kver` directories
|
||||
**Integration**: Uses `ostree_ext::bootabletree::find_kernel_dir_fs`
|
||||
|
||||
### 5. utf8 Lint (Recursive)
|
||||
|
||||
```rust
|
||||
// From lints.rs:489-522
|
||||
static LINT_UTF8: Lint = Lint {
|
||||
name: "utf8",
|
||||
description: "Check for non-UTF8 filenames...",
|
||||
ty: LintType::Fatal,
|
||||
root_type: None,
|
||||
f: LintFnTy::Recursive(check_utf8),
|
||||
};
|
||||
```
|
||||
|
||||
**Purpose**: Ensures all filenames and symlink targets are UTF-8
|
||||
**Check**: Recursively validates filesystem entries
|
||||
**Features**: Handles symlinks, broken links, and special cases
|
||||
|
||||
### 6. api-base-directories Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:535-558
|
||||
static LINT_API_DIRS: Lint = Lint::new_fatal(
|
||||
"api-base-directories",
|
||||
"Verify that expected base API directories exist...",
|
||||
check_api_dirs,
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Validates required systemd API directories
|
||||
**Check**: Ensures `/dev`, `/proc`, `/sys`, `/run`, `/tmp`, `/var` exist
|
||||
**Rationale**: Required by systemd and Linux standards
|
||||
|
||||
### 7. baseimage-root Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:610-632
|
||||
static LINT_BASEIMAGE_ROOT: Lint = Lint::new_fatal(
|
||||
"baseimage-root",
|
||||
"Check that expected files are present in the root...",
|
||||
check_baseimage_root,
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Validates bootc-specific root structure
|
||||
**Check**: Ensures `/sysroot` exists and `/ostree` symlinks correctly
|
||||
**Integration**: Checks embedded documentation for consistency
|
||||
|
||||
## Warning Lints
|
||||
|
||||
### 1. buildah-injected Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:412-433
|
||||
static LINT_BUILDAH_INJECTED: Lint = Lint::new_warning(
|
||||
"buildah-injected",
|
||||
"Check for an invalid /etc/hostname or /etc/resolv.conf...",
|
||||
check_buildah_injected,
|
||||
)
|
||||
.set_root_type(RootType::Alternative);
|
||||
```
|
||||
|
||||
**Purpose**: Detects empty files injected by build systems
|
||||
**Check**: Looks for empty `/etc/hostname` or `/etc/resolv.conf`
|
||||
**Scope**: Only applies to alternative roots (container images)
|
||||
|
||||
### 2. baseimage-composefs Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:560-581
|
||||
static LINT_COMPOSEFS: Lint = Lint::new_warning(
|
||||
"baseimage-composefs",
|
||||
"Check that composefs is enabled for ostree...",
|
||||
check_composefs,
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Recommends composefs for ostree
|
||||
**Check**: Validates composefs configuration
|
||||
**Integration**: Uses `ostree_prepareroot` for configuration parsing
|
||||
|
||||
### 3. var-log Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:656-682
|
||||
static LINT_VARLOG: Lint = Lint::new_warning(
|
||||
"var-log",
|
||||
"Check for non-empty regular files in /var/log...",
|
||||
check_varlog,
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Warns about log files in container images
|
||||
**Check**: Identifies non-empty files in `/var/log`
|
||||
**Features**: Recursive directory scanning with size checking
|
||||
|
||||
### 4. var-tmpfiles Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:684-712
|
||||
static LINT_VAR_TMPFILES: Lint = Lint::new_warning(
|
||||
"var-tmpfiles",
|
||||
"Check for content in /var that does not have corresponding systemd tmpfiles.d entries...",
|
||||
check_var_tmpfiles,
|
||||
)
|
||||
.set_root_type(RootType::Running);
|
||||
```
|
||||
|
||||
**Purpose**: Validates tmpfiles.d configuration
|
||||
**Check**: Ensures `/var` content has corresponding tmpfiles.d entries
|
||||
**Scope**: Only applies to running systems
|
||||
**Integration**: Uses `bootc_tmpfiles` crate
|
||||
|
||||
### 5. sysusers Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:714-743
|
||||
static LINT_SYSUSERS: Lint = Lint::new_warning(
|
||||
"sysusers",
|
||||
"Check for users in /etc/passwd and groups in /etc/group...",
|
||||
check_sysusers,
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Validates user/group definitions
|
||||
**Check**: Ensures sysusers.d entries exist for passwd/group entries
|
||||
**Integration**: Uses `bootc_sysusers` crate
|
||||
|
||||
### 6. nonempty-boot Lint
|
||||
|
||||
```rust
|
||||
// From lints.rs:745-773
|
||||
static LINT_NONEMPTY_BOOT: Lint = Lint::new_warning(
|
||||
"nonempty-boot",
|
||||
"The /boot directory should be present, but empty...",
|
||||
check_boot,
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Warns about content in `/boot` directory
|
||||
**Check**: Ensures `/boot` is empty in container images
|
||||
**Rationale**: Kernel content should be in `/usr/lib/modules`
|
||||
|
||||
## Configuration and Options
|
||||
|
||||
### 1. LintExecutionConfig
|
||||
|
||||
```rust
|
||||
// From lints.rs:69-72
|
||||
struct LintExecutionConfig {
|
||||
no_truncate: bool,
|
||||
}
|
||||
```
|
||||
|
||||
**no_truncate**: Controls output truncation (default: false, shows 5 items)
|
||||
|
||||
### 2. WarningDisposition
|
||||
|
||||
```rust
|
||||
// From lints.rs:101-104
|
||||
enum WarningDisposition {
|
||||
AllowWarnings, // Warnings don't fail the build
|
||||
FatalWarnings, // Warnings are treated as fatal
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Controls how warnings are handled
|
||||
**Default**: AllowWarnings
|
||||
|
||||
### 3. RootType
|
||||
|
||||
```rust
|
||||
// From lints.rs:106-111
|
||||
enum RootType {
|
||||
Running, // Running system root
|
||||
Alternative, // Alternative/container root
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Determines which lints apply to which root types
|
||||
**Filtering**: Lints can be restricted to specific root types
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. LintError Type
|
||||
|
||||
```rust
|
||||
// From lints.rs:38-67
|
||||
struct LintError(String);
|
||||
|
||||
impl std::fmt::Display for LintError {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
f.write_str(&self.0)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Represents lint failures
|
||||
**Features**: Custom display implementation for formatted output
|
||||
|
||||
### 2. Result Types
|
||||
|
||||
```rust
|
||||
// From lints.rs:44
|
||||
type LintResult = Result<std::result::Result<(), LintError>>;
|
||||
```
|
||||
|
||||
**Outer Result**: Runtime errors (file system issues, etc.)
|
||||
**Inner Result**: Lint success/failure
|
||||
**Pattern**: `Ok(Ok(()))` = success, `Ok(Err(LintError))` = lint failure
|
||||
|
||||
### 3. Error Reporting
|
||||
|
||||
```rust
|
||||
// From lints.rs:340-356
|
||||
if let Err(e) = r {
|
||||
match lint.ty {
|
||||
LintType::Fatal => {
|
||||
writeln!(output, "Failed lint: {name}: {e}")?;
|
||||
fatal += 1;
|
||||
}
|
||||
LintType::Warning => {
|
||||
writeln!(output, "Lint warning: {name}: {e}")?;
|
||||
warnings += 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Format**: Consistent error message formatting
|
||||
**Categorization**: Separate handling for fatal vs warning errors
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
### 1. Early Termination
|
||||
|
||||
```rust
|
||||
// From lints.rs:300-303
|
||||
if recursive_lints.is_empty() {
|
||||
return Ok(ControlFlow::Break(()));
|
||||
}
|
||||
```
|
||||
|
||||
**Feature**: Stops processing when no recursive lints remain
|
||||
**Benefit**: Avoids unnecessary filesystem traversal
|
||||
|
||||
### 2. Lint Filtering
|
||||
|
||||
```rust
|
||||
// From lints.rs:265-275
|
||||
let (mut applicable_lints, skipped_lints): (Vec<_>, Vec<_>) = LINTS.iter().partition(|lint| {
|
||||
if skip.contains(lint.name) {
|
||||
return false;
|
||||
}
|
||||
if let Some(lint_root_type) = lint.root_type {
|
||||
if lint_root_type != root_type {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
true
|
||||
});
|
||||
```
|
||||
|
||||
**Feature**: Only runs applicable lints
|
||||
**Benefit**: Reduces execution time for irrelevant checks
|
||||
|
||||
### 3. Output Truncation
|
||||
|
||||
```rust
|
||||
// From lints.rs:221-233
|
||||
if config.no_truncate {
|
||||
// Show all items
|
||||
} else {
|
||||
// Show limited items with count
|
||||
if rest > 0 {
|
||||
writeln!(o, " ...and {rest} more")?;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Feature**: Configurable output length
|
||||
**Default**: 5 items per lint
|
||||
**Benefit**: Prevents overwhelming output for large issues
|
||||
|
||||
## Testing Framework
|
||||
|
||||
### 1. Test Fixtures
|
||||
|
||||
```rust
|
||||
// From lints.rs:788-814
|
||||
fn passing_fixture() -> Result<cap_std_ext::cap_tempfile::TempDir> {
|
||||
let root = cap_std_ext::cap_tempfile::tempdir(cap_std::ambient_authority())?;
|
||||
for d in API_DIRS {
|
||||
root.create_dir(d)?;
|
||||
}
|
||||
// ... setup valid filesystem structure
|
||||
Ok(root)
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Creates test filesystems for lint validation
|
||||
**Features**: Both passing and failing test cases
|
||||
|
||||
### 2. Individual Lint Tests
|
||||
|
||||
```rust
|
||||
// From lints.rs:816-828
|
||||
#[test]
|
||||
fn test_var_run() -> Result<()> {
|
||||
let root = &fixture()?;
|
||||
let config = &LintExecutionConfig::default();
|
||||
// Test passing case
|
||||
check_var_run(root, config).unwrap().unwrap();
|
||||
// Test failing case
|
||||
root.create_dir_all("var/run/foo")?;
|
||||
assert!(check_var_run(root, config).unwrap().is_err());
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Coverage**: Each lint has dedicated tests
|
||||
**Scenarios**: Both success and failure cases
|
||||
|
||||
### 3. Integration Tests
|
||||
|
||||
```rust
|
||||
// From lints.rs:844-889
|
||||
#[test]
|
||||
fn test_lint_inner() -> Result<()> {
|
||||
let root = &passing_fixture()?;
|
||||
let config = &LintExecutionConfig::default();
|
||||
let mut out = Vec::new();
|
||||
let root_type = RootType::Alternative;
|
||||
let r = lint_inner(root, root_type, config, [], &mut out).unwrap();
|
||||
// Verify results
|
||||
assert_eq!(r.passed, *ALTROOT_LINTS);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Tests the complete lint execution flow
|
||||
**Validation**: Verifies correct counting and categorization
|
||||
|
||||
## Integration Points
|
||||
|
||||
### 1. OSTree Integration
|
||||
|
||||
- Uses `ostree_ext::bootabletree` for kernel detection
|
||||
- Integrates with `ostree_prepareroot` for composefs validation
|
||||
- Leverages OSTree's filesystem understanding
|
||||
|
||||
### 2. Systemd Integration
|
||||
|
||||
- Validates systemd API directories
|
||||
- Checks tmpfiles.d configuration
|
||||
- Validates sysusers.d entries
|
||||
|
||||
### 3. Container Runtime Integration
|
||||
|
||||
- Designed for container build processes
|
||||
- Supports various root filesystem types
|
||||
- Handles container-specific issues
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Extensibility
|
||||
|
||||
- Plugin system for custom lints
|
||||
- Configuration file support
|
||||
- Custom output formats
|
||||
|
||||
### 2. Performance
|
||||
|
||||
- Parallel lint execution
|
||||
- Incremental checking
|
||||
- Caching mechanisms
|
||||
|
||||
### 3. Integration
|
||||
|
||||
- IDE integration
|
||||
- CI/CD pipeline optimization
|
||||
- Real-time feedback
|
||||
|
||||
This technical reference provides comprehensive understanding of the bootc lint system's architecture, implementation, and usage patterns.
|
||||
0
ostree.md
Normal file
0
ostree.md
Normal file
1068
rollback/bootc-rollback-external-commands.md
Normal file
1068
rollback/bootc-rollback-external-commands.md
Normal file
File diff suppressed because it is too large
Load diff
434
rollback/bootc-rollback-flowchart.md
Normal file
434
rollback/bootc-rollback-flowchart.md
Normal file
|
|
@ -0,0 +1,434 @@
|
|||
# bootc rollback - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc rollback` process flow, showing the decision points, operations, and state transitions involved in rolling back to a previous deployment.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc rollback │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize System │
|
||||
│ • Get storage interface │
|
||||
│ • Get OSTree repository │
|
||||
│ • Get current system status │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Rollback Operation │
|
||||
│ │
|
||||
│ • Call deploy::rollback() function │
|
||||
│ • Handle rollback logic │
|
||||
│ • Update deployment order │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Handle Soft Reboot │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --soft-reboot specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Configure ││ │ │ Skip Soft Reboot ││ │
|
||||
│ │ │ Soft Reboot ││ │ │ ││ │
|
||||
│ │ │ • Check ││ │ │ • Continue to apply check ││ │
|
||||
│ │ │ capability││ │ │ ││ │
|
||||
│ │ │ • Prepare ││ │ │ ││ │
|
||||
│ │ │ if needed ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Apply Changes │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --apply specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Reboot ││ │ │ Changes Staged ││ │
|
||||
│ │ │ System ││ │ │ ││ │
|
||||
│ │ │ • Execute ││ │ │ • Changes ready for next boot ││ │
|
||||
│ │ │ reboot ││ │ │ • No immediate action ││ │
|
||||
│ │ │ • Apply ││ │ │ • User can reboot manually ││ │
|
||||
│ │ │ changes ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Rollback completed successfully │
|
||||
│ • Deployment order updated │
|
||||
│ • System ready for next boot (if --apply) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Rollback Operation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Core Rollback Operation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Get System Status │
|
||||
│ │
|
||||
│ • Get booted deployment │
|
||||
│ • Get all deployments │
|
||||
│ • Get host status │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create New Specification │
|
||||
│ │
|
||||
│ • Clone current host specification │
|
||||
│ • Swap boot order (Default ↔ Rollback) │
|
||||
│ • Preserve other settings │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Transition │
|
||||
│ │
|
||||
│ • Validate state transition is allowed │
|
||||
│ • Check rollback availability │
|
||||
│ • Ensure valid operation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Operation Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ reverting = (boot_order == Default)? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Reverting ││ │ │ Rolling Back ││ │
|
||||
│ │ │ • Print: ││ │ │ ││ │
|
||||
│ │ │ "notice: ││ │ │ • Switch to rollback ││ │
|
||||
│ │ │ Reverting ││ │ │ deployment ││ │
|
||||
│ │ │ queued ││ │ │ • Make rollback first ││ │
|
||||
│ │ │ rollback ││ │ │ in boot order ││ │
|
||||
│ │ │ state" ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Validate Rollback Deployment │
|
||||
│ │
|
||||
│ • Check rollback deployment exists │
|
||||
│ • Verify rollback is container-based │
|
||||
│ • Get rollback image information │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Log Rollback Operation │
|
||||
│ │
|
||||
│ • Log to systemd journal with unique message ID │
|
||||
│ • Include rollback type (rollback/revert) │
|
||||
│ • Include image digests and commit hashes │
|
||||
│ • Include current image information │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Reorder Deployments │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ reverting? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Order: ││ │ │ Order: ││ │
|
||||
│ │ │ [current, ││ │ │ [rollback, current, others] ││ │
|
||||
│ │ │ rollback, ││ │ │ ││ │
|
||||
│ │ │ others] ││ │ │ • Put rollback first ││ │
|
||||
│ │ │ ││ │ │ • Put current second ││ │
|
||||
│ │ │ • Put ││ │ │ • Keep others in order ││ │
|
||||
│ │ │ current ││ │ │ ││ │
|
||||
│ │ │ first ││ │ │ ││ │
|
||||
│ │ │ • Put ││ │ │ ││ │
|
||||
│ │ │ rollback ││ │ │ ││ │
|
||||
│ │ │ second ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Write New Deployment Order │
|
||||
│ │
|
||||
│ • Write new deployment order to OSTree │
|
||||
│ • Update bootloader configuration │
|
||||
│ • Preserve other deployments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Provide User Feedback │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ reverting? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Print: ││ │ │ Print: ││ │
|
||||
│ │ │ "Next boot: ││ │ │ "Next boot: rollback ││ │
|
||||
│ │ │ current ││ │ │ deployment" ││ │
|
||||
│ │ │ deployment" ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Write Reboot Required Marker │
|
||||
│ │
|
||||
│ • Write reboot required marker │
|
||||
│ • Include rollback image digest │
|
||||
│ • Mark system for reboot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Update System Status │
|
||||
│ │
|
||||
│ • Update system modification time │
|
||||
│ • Refresh system status │
|
||||
│ • Update deployment information │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Rollback operation completed │
|
||||
│ • Deployment order updated │
|
||||
│ • System ready for next boot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Soft Reboot Rollback Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Soft Reboot Rollback │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Soft Reboot Capability │
|
||||
│ │
|
||||
│ • Verify rollback deployment supports soft reboot │
|
||||
│ • Check system soft reboot support │
|
||||
│ • Validate deployment compatibility │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Prepare Soft Reboot │
|
||||
│ │
|
||||
│ • Get rollback deployment list │
|
||||
│ • Find target rollback deployment │
|
||||
│ • Prepare soft reboot environment │
|
||||
│ • Configure kexec for soft reboot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Soft Reboot │
|
||||
│ │
|
||||
│ • Load rollback kernel into memory │
|
||||
│ • Prepare rollback initramfs │
|
||||
│ • Execute kexec for soft reboot │
|
||||
│ • Avoid full hardware reboot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Soft reboot completed │
|
||||
│ • System running rollback deployment │
|
||||
│ • Faster restart achieved │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Rollback │ │ System │ │ Soft Reboot │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • No rollback │ │ • Not bootc │ │ • Soft reboot │ │
|
||||
│ │ available │ │ compatible │ │ not supported │ │
|
||||
│ │ • Rollback not │ │ • Invalid │ │ • No rollback │ │
|
||||
│ │ container- │ │ transition │ │ deployment │ │
|
||||
│ │ based │ │ • Deployment │ │ found │ │
|
||||
│ │ • Invalid │ │ not found │ │ • kexec failed │ │
|
||||
│ │ rollback │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up any partial state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Current State │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Normal │ │ Rollback │ │
|
||||
│ │ State │ │ Queued │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Boot Order: │ │ • Boot Order: Rollback │ │
|
||||
│ │ Default │ │ • Current: Second │ │
|
||||
│ │ • Current: │ │ • Rollback: First │ │
|
||||
│ │ First │ │ • Next Boot: Rollback │ │
|
||||
│ │ • Rollback: │ │ │ │
|
||||
│ │ Second │ │ │ │
|
||||
│ │ • Next Boot: │ │ │ │
|
||||
│ │ Current │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Rollback Operation │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────────────────────┐ │ │
|
||||
│ │ │ Rollback │ │ Revert │ │ │
|
||||
│ │ │ (Normal → │ │ (Rollback → │ │ │
|
||||
│ │ │ Rollback) │ │ Normal) │ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ │ • Swap boot │ │ • Swap boot order │ │ │
|
||||
│ │ │ order │ │ • Return to normal │ │ │
|
||||
│ │ │ • Make rollback │ │ • Make current first │ │ │
|
||||
│ │ │ first │ │ • Make rollback second │ │ │
|
||||
│ │ │ • Make current │ │ │ │ │
|
||||
│ │ │ second │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ New State │ │ New State │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Boot Order: │ │ • Boot Order: Default │ │
|
||||
│ │ Rollback │ │ • Current: First │ │
|
||||
│ │ • Current: │ │ • Rollback: Second │ │
|
||||
│ │ Second │ │ • Next Boot: Current │ │
|
||||
│ │ • Rollback: │ │ │ │
|
||||
│ │ First │ │ │ │
|
||||
│ │ • Next Boot: │ │ │ │
|
||||
│ │ Rollback │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Boot Order Management
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Boot Order States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Default Boot Order │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Current │ │ Rollback │ │
|
||||
│ │ Deployment │ │ Deployment │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • First in │ │ • Second in boot order │ │
|
||||
│ │ boot order │ │ • Backup deployment │ │
|
||||
│ │ • Active │ │ • Available for rollback │ │
|
||||
│ │ deployment │ │ │ │
|
||||
│ │ • Next boot │ │ │ │
|
||||
│ │ target │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Rollback Boot Order │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Rollback │ │ Current │ │
|
||||
│ │ Deployment │ │ Deployment │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • First in │ │ • Second in boot order │ │
|
||||
│ │ boot order │ │ • Previous deployment │ │
|
||||
│ │ • Next boot │ │ • Available for future rollback │ │
|
||||
│ │ target │ │ │ │
|
||||
│ │ • Active │ │ │ │
|
||||
│ │ deployment │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc rollback process, showing all decision points, operations, and state transitions involved in rolling back to a previous deployment.
|
||||
632
rollback/bootc-rollback-technical-guide.md
Normal file
632
rollback/bootc-rollback-technical-guide.md
Normal file
|
|
@ -0,0 +1,632 @@
|
|||
# bootc rollback - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc rollback` is a command for reverting to a previous deployment in a bootc-managed system. It changes the bootloader entry ordering to make the rollback deployment the next boot target, while preserving the current deployment as the new rollback target. This provides a safety mechanism for quickly reverting problematic updates.
|
||||
|
||||
## Purpose
|
||||
|
||||
The rollback command serves several critical functions:
|
||||
|
||||
1. **Deployment Reversion**: Revert to a previous working deployment
|
||||
2. **Safety Mechanism**: Quick recovery from problematic updates
|
||||
3. **Boot Order Management**: Change bootloader entry ordering
|
||||
4. **State Preservation**: Maintain deployment history
|
||||
5. **Emergency Recovery**: Fast system recovery from failures
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc rollback [OPTIONS...]
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Rollback to previous deployment
|
||||
bootc rollback
|
||||
|
||||
# Rollback and apply immediately
|
||||
bootc rollback --apply
|
||||
|
||||
# Rollback with soft reboot
|
||||
bootc rollback --apply --soft-reboot=auto
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
| Option | Description | Default | Required |
|
||||
|--------|-------------|---------|----------|
|
||||
| `--apply` | Restart/reboot into rollback image | `false` | No |
|
||||
| `--soft-reboot` | Configure soft reboot behavior | `None` | No |
|
||||
|
||||
### Soft Reboot Modes
|
||||
|
||||
| Mode | Description | Behavior |
|
||||
|------|-------------|----------|
|
||||
| `required` | Fail if soft reboot unavailable | Error if not supported |
|
||||
| `auto` | Use soft reboot if available | Fallback to regular reboot |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 1. Rollback Command Structure
|
||||
|
||||
```rust
|
||||
pub(crate) struct RollbackOpts {
|
||||
pub(crate) apply: bool, // Apply and reboot
|
||||
pub(crate) soft_reboot: Option<SoftRebootMode>, // Soft reboot behavior
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Rollback Process Flow
|
||||
|
||||
```rust
|
||||
async fn rollback(opts: RollbackOpts) -> Result<()> {
|
||||
// 1. Get system storage and OSTree
|
||||
let sysroot = &get_storage().await?;
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
|
||||
// 2. Execute rollback operation
|
||||
crate::deploy::rollback(sysroot).await?;
|
||||
|
||||
// 3. Handle soft reboot if requested
|
||||
if opts.soft_reboot.is_some() {
|
||||
let host = crate::status::get_status_require_booted(ostree)?.2;
|
||||
handle_soft_reboot(
|
||||
opts.soft_reboot,
|
||||
host.status.rollback.as_ref(),
|
||||
"rollback",
|
||||
|| soft_reboot_rollback(ostree),
|
||||
)?;
|
||||
}
|
||||
|
||||
// 4. Apply changes if requested
|
||||
if opts.apply {
|
||||
crate::reboot::reboot()?;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Core Rollback Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) async fn rollback(sysroot: &Storage) -> Result<()> {
|
||||
const ROLLBACK_JOURNAL_ID: &str = "26f3b1eb24464d12aa5e7b544a6b5468";
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let (booted_deployment, deployments, host) =
|
||||
crate::status::get_status_require_booted(ostree)?;
|
||||
|
||||
// 1. Create new specification with swapped boot order
|
||||
let new_spec = {
|
||||
let mut new_spec = host.spec.clone();
|
||||
new_spec.boot_order = new_spec.boot_order.swap();
|
||||
new_spec
|
||||
};
|
||||
|
||||
// 2. Verify transition is valid
|
||||
host.spec.verify_transition(&new_spec)?;
|
||||
|
||||
// 3. Determine if reverting or rolling back
|
||||
let reverting = new_spec.boot_order == BootOrder::Default;
|
||||
if reverting {
|
||||
println!("notice: Reverting queued rollback state");
|
||||
}
|
||||
|
||||
// 4. Get rollback deployment information
|
||||
let rollback_status = host.status.rollback
|
||||
.ok_or_else(|| anyhow!("No rollback available"))?;
|
||||
let rollback_image = rollback_status
|
||||
.query_image(repo)?
|
||||
.ok_or_else(|| anyhow!("Rollback is not container image based"))?;
|
||||
|
||||
// 5. Get current booted image for comparison
|
||||
let current_image = host.status.booted
|
||||
.as_ref()
|
||||
.and_then(|b| b.query_image(repo).ok()?);
|
||||
|
||||
// 6. Log rollback operation
|
||||
tracing::info!(
|
||||
message_id = ROLLBACK_JOURNAL_ID,
|
||||
bootc.manifest_digest = rollback_image.manifest_digest.as_ref(),
|
||||
bootc.ostree_commit = &rollback_image.merge_commit,
|
||||
bootc.rollback_type = if reverting { "revert" } else { "rollback" },
|
||||
bootc.current_manifest_digest = current_image
|
||||
.as_ref()
|
||||
.map(|i| i.manifest_digest.as_ref())
|
||||
.unwrap_or("none"),
|
||||
"Rolling back to image: {}",
|
||||
rollback_image.manifest_digest
|
||||
);
|
||||
|
||||
// 7. Reorder deployments
|
||||
let rollback_deployment = deployments.rollback.expect("rollback deployment");
|
||||
let new_deployments = if reverting {
|
||||
[booted_deployment, rollback_deployment]
|
||||
} else {
|
||||
[rollback_deployment, booted_deployment]
|
||||
};
|
||||
let new_deployments = new_deployments
|
||||
.into_iter()
|
||||
.chain(deployments.other)
|
||||
.collect::<Vec<_>>();
|
||||
|
||||
// 8. Write new deployment order
|
||||
ostree.write_deployments(&new_deployments, gio::Cancellable::NONE)?;
|
||||
|
||||
// 9. Provide user feedback
|
||||
if reverting {
|
||||
println!("Next boot: current deployment");
|
||||
} else {
|
||||
println!("Next boot: rollback deployment");
|
||||
}
|
||||
|
||||
// 10. Write reboot required marker
|
||||
write_reboot_required(rollback_image.manifest_digest.as_ref())?;
|
||||
|
||||
// 11. Update system status
|
||||
sysroot.update_mtime()?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Boot Order Management
|
||||
|
||||
### 1. Boot Order States
|
||||
|
||||
The rollback system manages two boot order states:
|
||||
|
||||
#### Default Boot Order
|
||||
- **Current Deployment**: First in boot order
|
||||
- **Rollback Deployment**: Second in boot order
|
||||
- **State**: Normal operation
|
||||
|
||||
#### Rollback Boot Order
|
||||
- **Rollback Deployment**: First in boot order
|
||||
- **Current Deployment**: Second in boot order
|
||||
- **State**: Rollback queued for next boot
|
||||
|
||||
### 2. Boot Order Swapping
|
||||
|
||||
```rust
|
||||
let new_spec = {
|
||||
let mut new_spec = host.spec.clone();
|
||||
new_spec.boot_order = new_spec.boot_order.swap();
|
||||
new_spec
|
||||
};
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. **Clone Current Spec**: Copy existing host specification
|
||||
2. **Swap Boot Order**: Change boot order state
|
||||
3. **Preserve Other Settings**: Keep image and other settings
|
||||
|
||||
### 3. Reversion Detection
|
||||
|
||||
```rust
|
||||
let reverting = new_spec.boot_order == BootOrder::Default;
|
||||
if reverting {
|
||||
println!("notice: Reverting queued rollback state");
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Detect if rolling back to normal state or rolling back to previous deployment
|
||||
**Behavior**:
|
||||
- **Rollback**: Switch to rollback deployment
|
||||
- **Revert**: Return to normal boot order
|
||||
|
||||
## Deployment Reordering
|
||||
|
||||
### 1. Deployment Array Management
|
||||
|
||||
```rust
|
||||
let new_deployments = if reverting {
|
||||
[booted_deployment, rollback_deployment]
|
||||
} else {
|
||||
[rollback_deployment, booted_deployment]
|
||||
};
|
||||
let new_deployments = new_deployments
|
||||
.into_iter()
|
||||
.chain(deployments.other)
|
||||
.collect::<Vec<_>>();
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. **Determine Order**: Based on reverting flag
|
||||
2. **Reorder Deployments**: Put target deployment first
|
||||
3. **Preserve Others**: Keep other deployments in order
|
||||
4. **Create Array**: Build new deployment array
|
||||
|
||||
### 2. OSTree Deployment Writing
|
||||
|
||||
```rust
|
||||
ostree.write_deployments(&new_deployments, gio::Cancellable::NONE)?;
|
||||
```
|
||||
|
||||
**Purpose**: Write new deployment order to OSTree
|
||||
**Process**: Update bootloader configuration with new deployment order
|
||||
|
||||
## Logging and Monitoring
|
||||
|
||||
### 1. Rollback Operation Logging
|
||||
|
||||
```rust
|
||||
const ROLLBACK_JOURNAL_ID: &str = "26f3b1eb24464d12aa5e7b544a6b5468";
|
||||
|
||||
tracing::info!(
|
||||
message_id = ROLLBACK_JOURNAL_ID,
|
||||
bootc.manifest_digest = rollback_image.manifest_digest.as_ref(),
|
||||
bootc.ostree_commit = &rollback_image.merge_commit,
|
||||
bootc.rollback_type = if reverting { "revert" } else { "rollback" },
|
||||
bootc.current_manifest_digest = current_image
|
||||
.as_ref()
|
||||
.map(|i| i.manifest_digest.as_ref())
|
||||
.unwrap_or("none"),
|
||||
"Rolling back to image: {}",
|
||||
rollback_image.manifest_digest
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Track rollback operations
|
||||
**Fields**:
|
||||
- `message_id`: Unique identifier for rollback operations
|
||||
- `bootc.manifest_digest`: Target rollback image digest
|
||||
- `bootc.ostree_commit`: OSTree commit hash
|
||||
- `bootc.rollback_type`: Operation type (rollback or revert)
|
||||
- `bootc.current_manifest_digest`: Current image digest
|
||||
|
||||
### 2. User Feedback
|
||||
|
||||
```rust
|
||||
if reverting {
|
||||
println!("Next boot: current deployment");
|
||||
} else {
|
||||
println!("Next boot: rollback deployment");
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Inform user about next boot target
|
||||
**Messages**:
|
||||
- **Reverting**: "Next boot: current deployment"
|
||||
- **Rolling Back**: "Next boot: rollback deployment"
|
||||
|
||||
## Soft Reboot Support
|
||||
|
||||
### 1. Soft Reboot Rollback
|
||||
|
||||
```rust
|
||||
fn soft_reboot_rollback(sysroot: &SysrootLock) -> Result<()> {
|
||||
println!("Rollback deployment is soft-reboot capable, preparing for soft-reboot...");
|
||||
|
||||
let deployments_list = sysroot.deployments();
|
||||
let target_deployment = deployments_list
|
||||
.first()
|
||||
.ok_or_else(|| anyhow::anyhow!("No rollback deployment found!"))?;
|
||||
|
||||
prepare_soft_reboot(sysroot, target_deployment)
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Prepare rollback deployment for soft reboot
|
||||
**Process**:
|
||||
1. **Check Capability**: Verify soft reboot support
|
||||
2. **Get Target**: Find rollback deployment
|
||||
3. **Prepare**: Set up soft reboot environment
|
||||
|
||||
### 2. Soft Reboot Handling
|
||||
|
||||
```rust
|
||||
if opts.soft_reboot.is_some() {
|
||||
let host = crate::status::get_status_require_booted(ostree)?.2;
|
||||
handle_soft_reboot(
|
||||
opts.soft_reboot,
|
||||
host.status.rollback.as_ref(),
|
||||
"rollback",
|
||||
|| soft_reboot_rollback(ostree),
|
||||
)?;
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Handle soft reboot configuration
|
||||
**Process**:
|
||||
1. **Check Status**: Get current system status
|
||||
2. **Handle Soft Reboot**: Configure if supported
|
||||
3. **Fallback**: Use regular reboot if not supported
|
||||
|
||||
## State Management
|
||||
|
||||
### 1. Rollback Availability Check
|
||||
|
||||
```rust
|
||||
let rollback_status = host.status.rollback
|
||||
.ok_or_else(|| anyhow!("No rollback available"))?;
|
||||
```
|
||||
|
||||
**Purpose**: Ensure rollback deployment exists
|
||||
**Error**: Fails if no rollback deployment available
|
||||
|
||||
### 2. Image Validation
|
||||
|
||||
```rust
|
||||
let rollback_image = rollback_status
|
||||
.query_image(repo)?
|
||||
.ok_or_else(|| anyhow!("Rollback is not container image based"))?;
|
||||
```
|
||||
|
||||
**Purpose**: Validate rollback deployment is container-based
|
||||
**Error**: Fails if rollback is not container image based
|
||||
|
||||
### 3. Transition Verification
|
||||
|
||||
```rust
|
||||
host.spec.verify_transition(&new_spec)?;
|
||||
```
|
||||
|
||||
**Purpose**: Ensure rollback transition is valid
|
||||
**Process**: Validate state transition is allowed
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Rollback Availability Errors
|
||||
|
||||
```rust
|
||||
// No rollback available
|
||||
Error: No rollback available
|
||||
|
||||
// Rollback not container-based
|
||||
Error: Rollback is not container image based
|
||||
```
|
||||
|
||||
### 2. System State Errors
|
||||
|
||||
```rust
|
||||
// System not bootc compatible
|
||||
Error: System is not bootc compatible
|
||||
|
||||
// Invalid transition
|
||||
Error: Invalid state transition
|
||||
```
|
||||
|
||||
### 3. Soft Reboot Errors
|
||||
|
||||
```rust
|
||||
// Soft reboot not supported
|
||||
Error: Soft reboot not available
|
||||
|
||||
// No rollback deployment found
|
||||
Error: No rollback deployment found!
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### 1. Emergency Rollback
|
||||
|
||||
```bash
|
||||
# Quick rollback to previous deployment
|
||||
bootc rollback --apply
|
||||
|
||||
# Rollback with soft reboot
|
||||
bootc rollback --apply --soft-reboot=auto
|
||||
```
|
||||
|
||||
### 2. Rollback Preparation
|
||||
|
||||
```bash
|
||||
# Prepare rollback for next boot
|
||||
bootc rollback
|
||||
|
||||
# Check status
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 3. Reversion
|
||||
|
||||
```bash
|
||||
# Revert rollback state
|
||||
bootc rollback
|
||||
|
||||
# Apply reversion
|
||||
bootc rollback --apply
|
||||
```
|
||||
|
||||
## Integration with Other Commands
|
||||
|
||||
### 1. Relationship to bootc upgrade
|
||||
|
||||
**Complementary**:
|
||||
- `upgrade`: Deploy new updates
|
||||
- `rollback`: Revert to previous deployment
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Deploy update
|
||||
bootc upgrade --apply
|
||||
|
||||
# If issues, rollback
|
||||
bootc rollback --apply
|
||||
```
|
||||
|
||||
### 2. Relationship to bootc switch
|
||||
|
||||
**Complementary**:
|
||||
- `switch`: Change image source
|
||||
- `rollback`: Revert to previous deployment
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Switch to new image
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# If issues, rollback
|
||||
bootc rollback --apply
|
||||
```
|
||||
|
||||
### 3. Relationship to bootc status
|
||||
|
||||
**Status Display**:
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Perform rollback
|
||||
bootc rollback
|
||||
|
||||
# Check updated status
|
||||
bootc status
|
||||
```
|
||||
|
||||
## /etc Directory Behavior
|
||||
|
||||
### 1. /etc State Preservation
|
||||
|
||||
**Important Note**: When performing a rollback, changes made to files in the `/etc` directory won't carry over to the rolled-back deployment. The `/etc` files will revert to their state from that previous deployment.
|
||||
|
||||
### 2. Why /etc Changes Don't Persist
|
||||
|
||||
```rust
|
||||
// This is because `bootc rollback` just reorders the existing
|
||||
// deployments. It doesn't create new deployments. The `/etc`
|
||||
// merges happen when new deployments are created.
|
||||
```
|
||||
|
||||
**Reason**:
|
||||
- **Deployment Reordering**: Rollback only changes boot order
|
||||
- **No New Deployment**: Doesn't create new deployment
|
||||
- **No /etc Merge**: /etc merges happen during deployment creation
|
||||
|
||||
### 3. /etc State Management
|
||||
|
||||
**Current Deployment**:
|
||||
- `/etc` changes are preserved
|
||||
- Local modifications remain
|
||||
|
||||
**Rollback Deployment**:
|
||||
- `/etc` state from previous deployment
|
||||
- No local modifications from current deployment
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Rollback Validation
|
||||
|
||||
- **Deployment Existence**: Verify rollback deployment exists
|
||||
- **Image Compatibility**: Ensure rollback is container-based
|
||||
- **Transition Safety**: Validate state transitions
|
||||
|
||||
### 2. State Consistency
|
||||
|
||||
- **Atomic Operations**: All-or-nothing rollback operations
|
||||
- **Status Updates**: Consistent system status updates
|
||||
- **Logging**: Comprehensive operation logging
|
||||
|
||||
### 3. Access Control
|
||||
|
||||
- **Privilege Requirements**: Appropriate system privileges
|
||||
- **Deployment Access**: Access to deployment information
|
||||
- **Bootloader Control**: Bootloader configuration access
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Rollback Speed
|
||||
|
||||
- **No Image Download**: Rollback doesn't download images
|
||||
- **Deployment Reordering**: Only changes boot order
|
||||
- **Fast Execution**: Quick rollback operations
|
||||
|
||||
### 2. State Management
|
||||
|
||||
- **Minimal Changes**: Only reorders existing deployments
|
||||
- **Preserved State**: Maintains deployment history
|
||||
- **Efficient Updates**: Minimal system updates
|
||||
|
||||
### 3. Boot Time
|
||||
|
||||
- **No Impact**: Rollback doesn't affect boot time
|
||||
- **Same Images**: Uses existing deployments
|
||||
- **Normal Boot**: Standard boot process
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### No Rollback Available
|
||||
```bash
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check deployment history
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
#### Rollback Not Container-Based
|
||||
```bash
|
||||
# Check rollback deployment
|
||||
bootc status --json | jq '.status.rollback'
|
||||
|
||||
# Check deployment type
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
#### Soft Reboot Fails
|
||||
```bash
|
||||
# Use regular reboot
|
||||
bootc rollback --apply
|
||||
|
||||
# Check soft reboot support
|
||||
bootc rollback --apply --soft-reboot=required
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc rollback
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Check deployment status
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Rollback Strategy
|
||||
|
||||
- **Test Rollbacks**: Test rollback procedures regularly
|
||||
- **Monitor Deployments**: Keep track of deployment history
|
||||
- **Quick Response**: Be prepared for quick rollbacks
|
||||
- **Documentation**: Document rollback procedures
|
||||
|
||||
### 2. System Management
|
||||
|
||||
- **Regular Backups**: Backup important /etc configurations
|
||||
- **Deployment Monitoring**: Monitor deployment health
|
||||
- **Rollback Testing**: Test rollback procedures
|
||||
- **Recovery Planning**: Plan for rollback scenarios
|
||||
|
||||
### 3. Integration
|
||||
|
||||
- **Automated Monitoring**: Monitor for rollback needs
|
||||
- **Alert Systems**: Alert on rollback operations
|
||||
- **Documentation**: Document rollback procedures
|
||||
- **Training**: Train operators on rollback procedures
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Userspace Restart**: For kernel-unchanged rollbacks
|
||||
- **Rollback Automation**: Automatic rollback on failure
|
||||
- **Rollback Scheduling**: Time-based rollback operations
|
||||
- **Health Checks**: Pre/post rollback validation
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for rollback operations
|
||||
- **Web Interface**: Web-based rollback management
|
||||
- **Configuration Management**: Declarative rollback control
|
||||
- **Audit Logging**: Comprehensive audit trails
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc rollback system's architecture, implementation, and usage patterns.
|
||||
702
state/bootc-state-examples-troubleshooting.md
Normal file
702
state/bootc-state-examples-troubleshooting.md
Normal file
|
|
@ -0,0 +1,702 @@
|
|||
# bootc state - Examples and Troubleshooting
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides practical examples and troubleshooting guidance for the `bootc state` system, covering common use cases, error scenarios, and debugging techniques.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. System Recovery
|
||||
|
||||
#### Complete System Reset
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Complete system reset script
|
||||
|
||||
echo "=== Bootc System Reset ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check current state
|
||||
echo "Current system state:"
|
||||
bootc status
|
||||
|
||||
# Confirm reset
|
||||
read -p "Are you sure you want to reset the system? (yes/no): " confirm
|
||||
if [ "$confirm" != "yes" ]; then
|
||||
echo "Reset cancelled"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Wipe all OSTree deployments
|
||||
echo "Wiping all OSTree deployments..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Verify wipe
|
||||
echo "Verifying wipe..."
|
||||
bootc status
|
||||
|
||||
# Check OSTree status
|
||||
echo "OSTree status:"
|
||||
ostree admin status
|
||||
|
||||
echo "System reset complete"
|
||||
```
|
||||
|
||||
#### Recovery from Corrupted State
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Recovery from corrupted state
|
||||
|
||||
echo "=== Bootc System Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system state
|
||||
echo "Checking system state..."
|
||||
if ! bootc status > /dev/null 2>&1; then
|
||||
echo "System state is corrupted, attempting recovery..."
|
||||
|
||||
# Try to fix OSTree repository
|
||||
echo "Attempting to fix OSTree repository..."
|
||||
ostree fsck --repair
|
||||
|
||||
# If repair fails, wipe and reinstall
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Repair failed, wiping system..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
echo "System wiped, ready for fresh installation"
|
||||
echo "Run: bootc install to-disk /dev/sda"
|
||||
else
|
||||
echo "Repository repaired successfully"
|
||||
fi
|
||||
else
|
||||
echo "System state is healthy"
|
||||
fi
|
||||
```
|
||||
|
||||
### 2. Development and Testing
|
||||
|
||||
#### Test Environment Reset
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Test environment reset script
|
||||
|
||||
echo "=== Test Environment Reset ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check if running in test environment
|
||||
if [ ! -f /etc/test-environment ]; then
|
||||
echo "ERROR: Not running in test environment"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Wipe test deployments
|
||||
echo "Wiping test deployments..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Clean up test data
|
||||
echo "Cleaning up test data..."
|
||||
rm -rf /var/lib/bootc/test-*
|
||||
rm -rf /tmp/bootc-test-*
|
||||
|
||||
# Reset test configuration
|
||||
echo "Resetting test configuration..."
|
||||
rm -f /etc/bootc/test-config.toml
|
||||
|
||||
echo "Test environment reset complete"
|
||||
```
|
||||
|
||||
#### Automated Testing
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Automated testing script
|
||||
|
||||
echo "=== Automated Testing ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Test 1: Normal wipe
|
||||
echo "Test 1: Normal wipe"
|
||||
bootc state wipe-ostree
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✓ Normal wipe test passed"
|
||||
else
|
||||
echo "✗ Normal wipe test failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Test 2: Wipe with no deployments
|
||||
echo "Test 2: Wipe with no deployments"
|
||||
bootc state wipe-ostree
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✓ Wipe with no deployments test passed"
|
||||
else
|
||||
echo "✗ Wipe with no deployments test failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Test 3: Verify system state
|
||||
echo "Test 3: Verify system state"
|
||||
bootc status
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✓ System state verification passed"
|
||||
else
|
||||
echo "✗ System state verification failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "All tests passed"
|
||||
```
|
||||
|
||||
### 3. System Maintenance
|
||||
|
||||
#### Scheduled Maintenance
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Scheduled maintenance script
|
||||
|
||||
echo "=== Scheduled Maintenance ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system health
|
||||
echo "Checking system health..."
|
||||
if ! bootc status > /dev/null 2>&1; then
|
||||
echo "System health check failed, attempting recovery..."
|
||||
|
||||
# Try to fix system
|
||||
ostree fsck --repair
|
||||
|
||||
# If still failing, wipe and reinstall
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "System repair failed, wiping and reinstalling..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Reinstall system
|
||||
bootc install to-disk /dev/sda
|
||||
|
||||
echo "System reinstalled successfully"
|
||||
else
|
||||
echo "System repaired successfully"
|
||||
fi
|
||||
else
|
||||
echo "System health check passed"
|
||||
fi
|
||||
|
||||
# Log maintenance
|
||||
echo "Maintenance completed at $(date)" >> /var/log/bootc-maintenance.log
|
||||
```
|
||||
|
||||
#### Emergency Recovery
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Emergency recovery script
|
||||
|
||||
echo "=== Emergency Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check if system is bootable
|
||||
if ! systemctl is-system-running > /dev/null 2>&1; then
|
||||
echo "System is not running, attempting emergency recovery..."
|
||||
|
||||
# Mount root filesystem
|
||||
mount /dev/sda1 /mnt
|
||||
|
||||
# Change root and wipe deployments
|
||||
chroot /mnt bootc state wipe-ostree
|
||||
|
||||
# Unmount
|
||||
umount /mnt
|
||||
|
||||
echo "Emergency recovery completed"
|
||||
echo "System should be bootable now"
|
||||
else
|
||||
echo "System is running normally"
|
||||
fi
|
||||
```
|
||||
|
||||
### 4. System Migration
|
||||
|
||||
#### Migrate to New Configuration
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# System migration script
|
||||
|
||||
echo "=== System Migration ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Backup current configuration
|
||||
echo "Backing up current configuration..."
|
||||
cp -r /etc/bootc /etc/bootc.backup
|
||||
cp -r /var/lib/bootc /var/lib/bootc.backup
|
||||
|
||||
# Wipe current deployments
|
||||
echo "Wiping current deployments..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Install new configuration
|
||||
echo "Installing new configuration..."
|
||||
bootc install to-disk /dev/sda
|
||||
|
||||
# Verify new installation
|
||||
echo "Verifying new installation..."
|
||||
bootc status
|
||||
|
||||
echo "Migration completed successfully"
|
||||
```
|
||||
|
||||
#### Clean Installation
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Clean installation script
|
||||
|
||||
echo "=== Clean Installation ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Wipe existing deployments
|
||||
echo "Wiping existing deployments..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Clean up system
|
||||
echo "Cleaning up system..."
|
||||
rm -rf /var/lib/bootc/*
|
||||
rm -rf /etc/bootc/*
|
||||
|
||||
# Install fresh system
|
||||
echo "Installing fresh system..."
|
||||
bootc install to-disk /dev/sda
|
||||
|
||||
# Configure system
|
||||
echo "Configuring system..."
|
||||
bootc edit
|
||||
|
||||
echo "Clean installation completed"
|
||||
```
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### 1. Common Error Scenarios
|
||||
|
||||
#### Permission Denied Errors
|
||||
|
||||
**Error**: `Permission denied: This command must be executed as the root user`
|
||||
|
||||
**Cause**: Command executed without root privileges
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check current user
|
||||
whoami
|
||||
|
||||
# Switch to root
|
||||
sudo su -
|
||||
|
||||
# Or use sudo
|
||||
sudo bootc state wipe-ostree
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Check if running as root
|
||||
if [ "$EUID" -ne 0 ]; then
|
||||
echo "This script must be run as root"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### OSTree Not Available
|
||||
|
||||
**Error**: `OSTree not found`
|
||||
|
||||
**Cause**: OSTree package not installed
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Install OSTree
|
||||
apt update
|
||||
apt install ostree
|
||||
|
||||
# Verify installation
|
||||
ostree --version
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Check OSTree availability
|
||||
if ! command -v ostree &> /dev/null; then
|
||||
echo "OSTree is not installed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### System Not OSTree-Based
|
||||
|
||||
**Error**: `No OSTree deployments found`
|
||||
|
||||
**Cause**: System is not OSTree-based
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check if system is OSTree-based
|
||||
ostree admin status
|
||||
|
||||
# If not OSTree-based, install OSTree
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Check system type
|
||||
if ! ostree admin status > /dev/null 2>&1; then
|
||||
echo "System is not OSTree-based"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### OSTree Repository Corruption
|
||||
|
||||
**Error**: `OSTree repository corruption detected`
|
||||
|
||||
**Cause**: OSTree repository is corrupted
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Try to repair repository
|
||||
ostree fsck --repair
|
||||
|
||||
# If repair fails, wipe and reinstall
|
||||
if [ $? -ne 0 ]; then
|
||||
bootc state wipe-ostree
|
||||
bootc install to-disk /dev/sda
|
||||
fi
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Regular repository checks
|
||||
ostree fsck
|
||||
|
||||
# Backup important deployments
|
||||
ostree admin pin <deployment-id>
|
||||
```
|
||||
|
||||
### 2. Debugging Techniques
|
||||
|
||||
#### Enable Debug Logging
|
||||
|
||||
```bash
|
||||
# Set debug log level
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Run command with debug output
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Check debug logs
|
||||
journalctl -u bootc-* --since "1 hour ago" | grep DEBUG
|
||||
```
|
||||
|
||||
#### Verbose Output
|
||||
|
||||
```bash
|
||||
# Enable verbose output
|
||||
bootc state wipe-ostree --verbose
|
||||
|
||||
# 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
|
||||
ostree --version
|
||||
bootc --version
|
||||
|
||||
# Check system configuration
|
||||
cat /etc/os-release
|
||||
cat /proc/version
|
||||
cat /proc/cpuinfo | head -20
|
||||
```
|
||||
|
||||
#### OSTree Diagnostics
|
||||
|
||||
```bash
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check repository integrity
|
||||
ostree fsck
|
||||
|
||||
# List all references
|
||||
ostree refs
|
||||
|
||||
# Show commit details
|
||||
ostree show <commit-hash>
|
||||
|
||||
# Check repository contents
|
||||
ostree ls <commit-hash>
|
||||
```
|
||||
|
||||
### 3. Recovery Procedures
|
||||
|
||||
#### System Recovery
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# System recovery script
|
||||
|
||||
echo "=== System Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system status
|
||||
echo "Checking system status..."
|
||||
bootc status
|
||||
|
||||
# Check OSTree status
|
||||
echo "Checking OSTree status..."
|
||||
ostree admin status
|
||||
|
||||
# Check repository integrity
|
||||
echo "Checking repository integrity..."
|
||||
ostree fsck
|
||||
|
||||
# If errors found, attempt repair
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Repository errors detected, attempting repair..."
|
||||
ostree fsck --repair
|
||||
|
||||
# If repair fails, wipe and reinstall
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Repair failed, wiping and reinstalling..."
|
||||
bootc state wipe-ostree
|
||||
bootc install to-disk /dev/sda
|
||||
fi
|
||||
fi
|
||||
|
||||
# Verify system is working
|
||||
echo "Verifying system is working..."
|
||||
bootc status
|
||||
bootc status
|
||||
|
||||
echo "Recovery complete"
|
||||
```
|
||||
|
||||
#### Data Recovery
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Data recovery script
|
||||
|
||||
echo "=== Data Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check for available backups
|
||||
echo "Checking for available backups..."
|
||||
ls -la /var/lib/bootc/backups/
|
||||
|
||||
# List available deployments
|
||||
echo "Available deployments:"
|
||||
ostree admin status
|
||||
|
||||
# Check deployment history
|
||||
echo "Deployment history:"
|
||||
ostree log <deployment-id>
|
||||
|
||||
# Attempt to recover specific deployment
|
||||
echo "Attempting to recover deployment..."
|
||||
ostree admin deploy <deployment-id>
|
||||
|
||||
# Verify recovery
|
||||
echo "Verifying recovery..."
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 4. Performance Analysis
|
||||
|
||||
#### System Performance
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# System performance analysis
|
||||
|
||||
echo "=== System Performance Analysis ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system load
|
||||
echo "System load:"
|
||||
uptime
|
||||
|
||||
# Check memory usage
|
||||
echo "Memory usage:"
|
||||
free -h
|
||||
|
||||
# Check disk usage
|
||||
echo "Disk usage:"
|
||||
df -h
|
||||
|
||||
# Check I/O usage
|
||||
echo "I/O usage:"
|
||||
iotop -bn1
|
||||
|
||||
# Check process usage
|
||||
echo "Process usage:"
|
||||
top -bn1 | head -20
|
||||
```
|
||||
|
||||
#### Command Performance
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Command performance analysis
|
||||
|
||||
echo "=== Command Performance Analysis ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Time wipe operation
|
||||
echo "Timing wipe operation..."
|
||||
time bootc state wipe-ostree
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
### 5. Monitoring and Alerting
|
||||
|
||||
#### Health Check Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Health check script
|
||||
|
||||
HEALTH_STATUS=0
|
||||
|
||||
echo "=== Bootc State Health Check ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system status
|
||||
echo "Checking system status..."
|
||||
if ! bootc status > /dev/null 2>&1; then
|
||||
echo "ERROR: System status check failed"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Check OSTree status
|
||||
echo "Checking OSTree status..."
|
||||
if ! ostree admin status > /dev/null 2>&1; then
|
||||
echo "ERROR: OSTree status check failed"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Check repository integrity
|
||||
echo "Checking repository integrity..."
|
||||
if ! ostree fsck > /dev/null 2>&1; then
|
||||
echo "ERROR: Repository integrity check failed"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Check storage usage
|
||||
echo "Checking storage usage..."
|
||||
STORAGE_USAGE=$(df /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//')
|
||||
if [ $STORAGE_USAGE -gt 90 ]; then
|
||||
echo "ERROR: Storage usage is critical: ${STORAGE_USAGE}%"
|
||||
HEALTH_STATUS=1
|
||||
elif [ $STORAGE_USAGE -gt 80 ]; then
|
||||
echo "WARNING: Storage usage is high: ${STORAGE_USAGE}%"
|
||||
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-state\",
|
||||
\"severity\": \"$severity\",
|
||||
\"message\": \"$message\",
|
||||
\"timestamp\": \"$(date -Iseconds)\"
|
||||
}"
|
||||
}
|
||||
|
||||
# Check system health
|
||||
if ! /usr/local/bin/bootc-state-health-check.sh; then
|
||||
send_alert "critical" "Bootc state system health check failed"
|
||||
fi
|
||||
|
||||
# Check storage usage
|
||||
STORAGE_USAGE=$(df /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//')
|
||||
if [ $STORAGE_USAGE -gt 90 ]; then
|
||||
send_alert "critical" "Storage usage is critical: ${STORAGE_USAGE}%"
|
||||
elif [ $STORAGE_USAGE -gt 80 ]; then
|
||||
send_alert "warning" "Storage usage is high: ${STORAGE_USAGE}%"
|
||||
fi
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Usage Guidelines
|
||||
|
||||
- **Backup First**: Always backup important data before wiping
|
||||
- **Verify System**: Ensure system is OSTree-based before wiping
|
||||
- **Plan Recovery**: Have recovery plan ready
|
||||
- **Test First**: Test in non-production environment
|
||||
|
||||
### 2. Safety Measures
|
||||
|
||||
- **Confirmation**: Consider adding confirmation prompt
|
||||
- **Logging**: Log all wipe operations
|
||||
- **Monitoring**: Monitor system after wipe
|
||||
- **Documentation**: Document wipe procedures
|
||||
|
||||
### 3. Recovery Procedures
|
||||
|
||||
- **Fresh Install**: Plan for fresh installation
|
||||
- **Data Recovery**: Ensure data is backed up
|
||||
- **System Restore**: Have system restore plan
|
||||
- **Testing**: Test recovery procedures
|
||||
|
||||
This comprehensive examples and troubleshooting guide provides practical solutions for common issues and advanced debugging techniques for the bootc state system.
|
||||
949
state/bootc-state-external-commands.md
Normal file
949
state/bootc-state-external-commands.md
Normal file
|
|
@ -0,0 +1,949 @@
|
|||
# bootc state - External Commands Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive reference for all external commands used by `bootc state` operations. These commands are essential for understanding the dependencies and integration points of the bootc state system.
|
||||
|
||||
## Core Commands
|
||||
|
||||
### bootc
|
||||
|
||||
**Purpose**: Main bootc command for state operations
|
||||
**Usage**: `bootc state <subcommand> [options...]`
|
||||
**Dependencies**: None (core command)
|
||||
|
||||
#### State Subcommands
|
||||
- `bootc state wipe-ostree` - Remove all OSTree deployments
|
||||
- `bootc state help` - Show help information
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Wipe all OSTree deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Show help
|
||||
bootc state --help
|
||||
bootc state wipe-ostree --help
|
||||
```
|
||||
|
||||
## OSTree Commands
|
||||
|
||||
### ostree
|
||||
|
||||
**Purpose**: OSTree repository operations
|
||||
**Usage**: `ostree <subcommand> [options...]`
|
||||
**Dependencies**: ostree package
|
||||
|
||||
#### Repository Commands
|
||||
- `ostree admin status` - Show admin status
|
||||
- `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 pin` - Pin deployments
|
||||
- `ostree admin unpin` - Unpin deployments
|
||||
- `ostree admin deploy` - Deploy commits
|
||||
- `ostree admin rollback` - Rollback deployments
|
||||
- `ostree admin cleanup` - Clean up deployments
|
||||
- `ostree fsck` - Check repository integrity
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show current status
|
||||
ostree admin status
|
||||
|
||||
# List all references
|
||||
ostree refs
|
||||
|
||||
# Show commit details
|
||||
ostree show <commit-hash>
|
||||
|
||||
# List repository contents
|
||||
ostree ls <commit-hash>
|
||||
|
||||
# Show file contents
|
||||
ostree cat <commit-hash> /path/to/file
|
||||
|
||||
# Checkout files
|
||||
ostree checkout <commit-hash> /path/to/destination
|
||||
|
||||
# Deploy commit
|
||||
ostree admin deploy <commit-hash>
|
||||
|
||||
# Rollback deployment
|
||||
ostree admin rollback
|
||||
|
||||
# Clean up deployments
|
||||
ostree admin cleanup
|
||||
|
||||
# Check repository integrity
|
||||
ostree fsck
|
||||
```
|
||||
|
||||
### ostree-ext
|
||||
|
||||
**Purpose**: Extended OSTree operations
|
||||
**Usage**: `ostree-ext <subcommand> [options...]`
|
||||
**Dependencies**: ostree-ext package
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Container operations
|
||||
ostree-ext container pull quay.io/myorg/image:latest
|
||||
|
||||
# Repository operations
|
||||
ostree-ext repo create /path/to/repo
|
||||
|
||||
# Image operations
|
||||
ostree-ext image build /path/to/image
|
||||
```
|
||||
|
||||
## System Commands
|
||||
|
||||
### systemctl
|
||||
|
||||
**Purpose**: Systemd service management
|
||||
**Usage**: `systemctl <subcommand> [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
|
||||
- `systemctl daemon-reload` - Reload systemd configuration
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
## Filesystem Commands
|
||||
|
||||
### mount
|
||||
|
||||
**Purpose**: Filesystem mounting
|
||||
**Usage**: `mount [options...] <device> <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Mount filesystem
|
||||
mount /dev/sda1 /mnt
|
||||
|
||||
# Unmount filesystem
|
||||
umount /mnt
|
||||
|
||||
# Check mount points
|
||||
findmnt
|
||||
|
||||
# Mount with options
|
||||
mount -o ro,noexec /dev/sda1 /mnt
|
||||
```
|
||||
|
||||
### umount
|
||||
|
||||
**Purpose**: Unmount filesystems
|
||||
**Usage**: `umount [options...] <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Unmount filesystem
|
||||
umount /mnt
|
||||
|
||||
# Force unmount
|
||||
umount -f /mnt
|
||||
|
||||
# Lazy unmount
|
||||
umount -l /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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
### kill
|
||||
|
||||
**Purpose**: Send signals to processes
|
||||
**Usage**: `kill [options...] <pid>`
|
||||
**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
|
||||
```
|
||||
|
||||
### pkill
|
||||
|
||||
**Purpose**: Kill processes by name
|
||||
**Usage**: `pkill [options...] <pattern>`
|
||||
**Dependencies**: procps
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Kill by name
|
||||
pkill process_name
|
||||
|
||||
# Force kill by name
|
||||
pkill -9 process_name
|
||||
|
||||
# Kill by pattern
|
||||
pkill -f "pattern"
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Archive Commands
|
||||
|
||||
### tar
|
||||
|
||||
**Purpose**: Archive operations
|
||||
**Usage**: `tar [options...] <archive> [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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Network Commands
|
||||
|
||||
### curl
|
||||
|
||||
**Purpose**: HTTP client for registry operations
|
||||
**Usage**: `curl [options...] <url>`
|
||||
**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...] <url>`
|
||||
**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
|
||||
```
|
||||
|
||||
## Container Commands
|
||||
|
||||
### podman
|
||||
|
||||
**Purpose**: Container runtime
|
||||
**Usage**: `podman <subcommand> [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 <subcommand> [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 .
|
||||
```
|
||||
|
||||
## 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 <subcommand> [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 <subcommand> [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
|
||||
```
|
||||
|
||||
## 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 <command> [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
|
||||
```
|
||||
|
||||
## 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...] <device>`
|
||||
**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
|
||||
```
|
||||
|
||||
## Recovery Commands
|
||||
|
||||
### chroot
|
||||
|
||||
**Purpose**: Change root directory
|
||||
**Usage**: `chroot [options...] <directory> <command>`
|
||||
**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
|
||||
```
|
||||
|
||||
### mount
|
||||
|
||||
**Purpose**: Mount filesystems for recovery
|
||||
**Usage**: `mount [options...] <device> <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Mount root filesystem
|
||||
mount /dev/sda1 /mnt
|
||||
|
||||
# Mount boot filesystem
|
||||
mount /dev/sda2 /mnt/boot
|
||||
|
||||
# Mount with specific options
|
||||
mount -o ro /dev/sda1 /mnt
|
||||
```
|
||||
|
||||
### umount
|
||||
|
||||
**Purpose**: Unmount filesystems after recovery
|
||||
**Usage**: `umount [options...] <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Unmount filesystem
|
||||
umount /mnt
|
||||
|
||||
# Unmount all filesystems
|
||||
umount -a
|
||||
|
||||
# Force unmount
|
||||
umount -f /mnt
|
||||
```
|
||||
|
||||
This comprehensive reference covers all external commands used by the bootc state system, providing examples and usage patterns for each command.
|
||||
406
state/bootc-state-flowchart.md
Normal file
406
state/bootc-state-flowchart.md
Normal file
|
|
@ -0,0 +1,406 @@
|
|||
# bootc state - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc state` process flow, showing the decision points, operations, and system state changes involved in state modification operations.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Command Arguments │
|
||||
│ │
|
||||
│ • Parse state subcommand │
|
||||
│ • Validate arguments │
|
||||
│ • Check permissions │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Route to Subcommand │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Subcommand Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ wipe-ostree │ │
|
||||
│ │ │ │
|
||||
│ │ • Remove all OSTree deployments │ │
|
||||
│ │ • Reset system state │ │
|
||||
│ │ • Prepare for fresh installation │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • State modification completed successfully │
|
||||
│ • System state updated │
|
||||
│ • Deployments removed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## wipe-ostree Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ wipe-ostree Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Prerequisites │
|
||||
│ │
|
||||
│ • Verify root privileges │
|
||||
│ • Check OSTree availability │
|
||||
│ • Validate system state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize OSTree │
|
||||
│ │
|
||||
│ • Create OSTree sysroot instance │
|
||||
│ • Load sysroot configuration │
|
||||
│ • Prepare for operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Wipe Operation │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Wipe Operation │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Spawn Blocking Task │ │
|
||||
│ │ │ │
|
||||
│ │ • Move to blocking thread │ │
|
||||
│ │ • Execute OSTree operations │ │
|
||||
│ │ • Handle cancellable operations │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Write Empty Deployments │ │
|
||||
│ │ │ │
|
||||
│ │ • Call sysroot.write_deployments(&[]) │ │
|
||||
│ │ • Remove all deployment entries │ │
|
||||
│ │ • Update system state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Operation │
|
||||
│ │
|
||||
│ • Check operation success │
|
||||
│ • Verify deployments removed │
|
||||
│ • Update system state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • All OSTree deployments removed │
|
||||
│ • System state reset │
|
||||
│ • Ready for fresh installation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## System State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initial State │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ System with OSTree Deployments │ │
|
||||
│ │ │ │
|
||||
│ │ • Active deployments present │ │
|
||||
│ │ • Boot entries configured │ │
|
||||
│ │ • System state managed │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Execute wipe-ostree │ │
|
||||
│ │ │ │
|
||||
│ │ • Remove all deployments │ │
|
||||
│ │ • Clear boot entries │ │
|
||||
│ │ • Reset system state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Final State │ │
|
||||
│ │ │ │
|
||||
│ │ • No OSTree deployments │ │
|
||||
│ │ • No boot entries │ │
|
||||
│ │ • Clean system state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Permission │ │ OSTree │ │ System │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Not Root │ │ • Not Available │ │ • Not OSTree │ │
|
||||
│ │ • Access Denied │ │ • Load Failed │ │ • Corrupted │ │
|
||||
│ │ • Invalid User │ │ • Write Failed │ │ • Unavailable │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Log error details │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## OSTree Operations Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ OSTree Operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize Sysroot │
|
||||
│ │
|
||||
│ • Create OSTree::Sysroot::new_default() │
|
||||
│ • Load sysroot configuration │
|
||||
│ • Prepare for operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Operations │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Operation Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Write Deployments │ │
|
||||
│ │ │ │
|
||||
│ │ • Call write_deployments(&[]) │ │
|
||||
│ │ • Remove all deployment entries │ │
|
||||
│ │ • Update system metadata │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Results │
|
||||
│ │
|
||||
│ • Check operation success │
|
||||
│ • Verify deployments removed │
|
||||
│ • Update system state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • OSTree operations completed │
|
||||
│ • System state updated │
|
||||
│ • Deployments removed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Asynchronous Execution Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Asynchronous Execution │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Spawn Blocking Task │
|
||||
│ │
|
||||
│ • Create tokio::task::spawn_blocking │
|
||||
│ • Move sysroot to blocking thread │
|
||||
│ • Prepare for OSTree operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute in Blocking Context │
|
||||
│ │
|
||||
│ • Run OSTree operations │
|
||||
│ │ • sysroot.write_deployments(&[]) │
|
||||
│ │ • Handle cancellable operations │
|
||||
│ │ • Update system state │
|
||||
│ • Return results to async context │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Await Results │
|
||||
│ │
|
||||
│ • Wait for blocking task completion │
|
||||
│ • Handle any errors │
|
||||
│ • Return results to caller │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Asynchronous operation completed │
|
||||
│ • Results returned to caller │
|
||||
│ • System state updated │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## System Impact Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System Impact Analysis │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Before Wipe │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ System State │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Deployments │ │ Boot Entries │ │ System State │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Active │ │ • Grub entries │ │ • Managed │ │
|
||||
│ │ • Staged │ │ • Systemd │ │ • Configured │ │
|
||||
│ │ • Rollback │ │ • Bootloader │ │ • Tracked │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ During Wipe │
|
||||
│ │
|
||||
│ • Remove all deployments │
|
||||
│ • Clear boot entries │
|
||||
│ • Reset system state │
|
||||
│ • Update metadata │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ After Wipe │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ System State │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Deployments │ │ Boot Entries │ │ System State │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • None │ │ • None │ │ • Clean │ │
|
||||
│ │ • Removed │ │ • Cleared │ │ • Reset │ │
|
||||
│ │ • Wiped │ │ • Removed │ │ • Fresh │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Recovery Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Recovery Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Assess System State │
|
||||
│ │
|
||||
│ • Check if system is bootable │
|
||||
│ • Verify data integrity │
|
||||
│ • Determine recovery needs │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Recovery Options │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Recovery Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Fresh Install │ │ Restore │ │ Manual │ │
|
||||
│ │ │ │ Backup │ │ Recovery │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Install ││ │ │ Restore ││ │ │ Fix ││ │
|
||||
│ │ │ New System ││ │ │ From Backup ││ │ │ Manually ││ │
|
||||
│ │ │ Configure ││ │ │ Restore ││ │ │ Rebuild ││ │
|
||||
│ │ │ Deploy ││ │ │ Data ││ │ │ System ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Recovery │
|
||||
│ │
|
||||
│ • Test system bootability │
|
||||
│ • Verify data integrity │
|
||||
│ • Check system functionality │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • System recovered successfully │
|
||||
│ • Data integrity verified │
|
||||
│ • System functionality restored │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc state process, showing all decision points, operations, and state transitions involved in state modification operations.
|
||||
292
state/bootc-state-quick-reference.md
Normal file
292
state/bootc-state-quick-reference.md
Normal file
|
|
@ -0,0 +1,292 @@
|
|||
# bootc state - Quick Reference
|
||||
|
||||
## Command Summary
|
||||
|
||||
| Command | Purpose | Usage |
|
||||
|---------|---------|-------|
|
||||
| `wipe-ostree` | Remove all OSTree deployments | `bootc state wipe-ostree` |
|
||||
| `help` | Show help information | `bootc state --help` |
|
||||
|
||||
## Quick Commands
|
||||
|
||||
### Basic Operations
|
||||
```bash
|
||||
# Wipe all OSTree deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Show help
|
||||
bootc state --help
|
||||
bootc state wipe-ostree --help
|
||||
```
|
||||
|
||||
### System Status
|
||||
```bash
|
||||
# Check current state
|
||||
bootc status
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check system health
|
||||
bootc status && echo "System healthy"
|
||||
```
|
||||
|
||||
### Recovery Operations
|
||||
```bash
|
||||
# Complete system reset
|
||||
bootc state wipe-ostree && bootc install to-disk /dev/sda
|
||||
|
||||
# Emergency recovery
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Verify recovery
|
||||
bootc status
|
||||
```
|
||||
|
||||
## Common Options
|
||||
|
||||
| Option | Purpose | Example |
|
||||
|--------|---------|---------|
|
||||
| `--help` | Show help | `bootc state --help` |
|
||||
| `--verbose` | Verbose output | `bootc state wipe-ostree --verbose` |
|
||||
| `--quiet` | Quiet output | `bootc state wipe-ostree --quiet` |
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Meaning | Solution |
|
||||
|------|---------|----------|
|
||||
| 1 | General error | Check logs for details |
|
||||
| 2 | Permission denied | Run as root |
|
||||
| 3 | OSTree not available | Install OSTree |
|
||||
| 4 | System not OSTree-based | Install OSTree system |
|
||||
| 5 | Repository corruption | Repair or wipe repository |
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Permission Denied
|
||||
```bash
|
||||
# Check user
|
||||
whoami
|
||||
|
||||
# Run as root
|
||||
sudo bootc state wipe-ostree
|
||||
```
|
||||
|
||||
### OSTree Not Available
|
||||
```bash
|
||||
# Install OSTree
|
||||
apt install ostree
|
||||
|
||||
# Verify installation
|
||||
ostree --version
|
||||
```
|
||||
|
||||
### System Not OSTree-Based
|
||||
```bash
|
||||
# Check system type
|
||||
ostree admin status
|
||||
|
||||
# Install OSTree system
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### Repository Corruption
|
||||
```bash
|
||||
# Check repository
|
||||
ostree fsck
|
||||
|
||||
# Repair repository
|
||||
ostree fsck --repair
|
||||
|
||||
# If repair fails, wipe and reinstall
|
||||
bootc state wipe-ostree
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
## 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` |
|
||||
| OSTree repo | Repository data | `/var/lib/bootc/ostree/` |
|
||||
| System state | System state | `/var/lib/bootc/state/` |
|
||||
|
||||
## 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 disk usage
|
||||
df -h /var/lib/bootc
|
||||
```
|
||||
|
||||
### Monitor System
|
||||
```bash
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check repository integrity
|
||||
ostree fsck
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Root Privileges
|
||||
- All state commands require root privileges
|
||||
- Use `sudo` or switch to root user
|
||||
- Check current user with `whoami`
|
||||
|
||||
### Destructive Operations
|
||||
- This is a destructive operation that cannot be undone
|
||||
- Always backup important data before execution
|
||||
- Verify system can be reinstalled
|
||||
|
||||
### Safety Checks
|
||||
- Check system state before wiping
|
||||
- Ensure recovery plan is ready
|
||||
- Test in non-production environment
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Regular Maintenance
|
||||
- Check system health regularly
|
||||
- Monitor storage usage
|
||||
- Check repository integrity
|
||||
- Plan for recovery
|
||||
|
||||
### Development
|
||||
- Use test environments
|
||||
- Test commands before production
|
||||
- Document procedures
|
||||
- Monitor system health
|
||||
|
||||
### Production
|
||||
- Set up monitoring
|
||||
- Configure alerts
|
||||
- Regular backups
|
||||
- Document procedures
|
||||
|
||||
## Troubleshooting Steps
|
||||
|
||||
1. **Check system status**
|
||||
```bash
|
||||
bootc status
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
2. **Check logs**
|
||||
```bash
|
||||
journalctl -u bootc-* --since "1 hour ago"
|
||||
tail -f /var/log/bootc/main.log
|
||||
```
|
||||
|
||||
3. **Check resources**
|
||||
```bash
|
||||
df -h /var/lib/bootc
|
||||
free -h
|
||||
uptime
|
||||
```
|
||||
|
||||
4. **Run diagnostics**
|
||||
```bash
|
||||
ostree fsck
|
||||
bootc status
|
||||
```
|
||||
|
||||
5. **Check configuration**
|
||||
```bash
|
||||
cat /etc/bootc/config.toml
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
## Quick Scripts
|
||||
|
||||
### Health Check
|
||||
```bash
|
||||
#!/bin/bash
|
||||
bootc status && ostree admin status && echo "System healthy"
|
||||
```
|
||||
|
||||
### System Reset
|
||||
```bash
|
||||
#!/bin/bash
|
||||
bootc state wipe-ostree && echo "System reset complete"
|
||||
```
|
||||
|
||||
### Recovery
|
||||
```bash
|
||||
#!/bin/bash
|
||||
bootc state wipe-ostree && bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```bash
|
||||
#!/bin/bash
|
||||
df -h /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//'
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Systemd Service
|
||||
```bash
|
||||
# Create service file
|
||||
cat > /etc/systemd/system/bootc-state.service << EOF
|
||||
[Unit]
|
||||
Description=Bootc State Service
|
||||
After=multi-user.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/bin/bootc-state-script.sh
|
||||
User=root
|
||||
Group=root
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# Enable service
|
||||
systemctl daemon-reload
|
||||
systemctl enable bootc-state.service
|
||||
```
|
||||
|
||||
### Cron Job
|
||||
```bash
|
||||
# Add to crontab
|
||||
echo "0 2 * * * /usr/local/bin/bootc-state-maintenance.sh" | crontab -
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```bash
|
||||
# Check system health
|
||||
if ! bootc status > /dev/null 2>&1; then
|
||||
echo "WARNING: System status check failed"
|
||||
# Send alert
|
||||
fi
|
||||
```
|
||||
|
||||
This quick reference provides essential information for using the bootc state system effectively.
|
||||
504
state/bootc-state-technical-guide.md
Normal file
504
state/bootc-state-technical-guide.md
Normal file
|
|
@ -0,0 +1,504 @@
|
|||
# bootc state - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc state` is a hidden command that provides system state modification operations for bootc systems. Currently, it contains a single critical command: `wipe-ostree`, which removes all OSTree deployments from the system.
|
||||
|
||||
## Purpose
|
||||
|
||||
The state commands serve critical system management functions:
|
||||
|
||||
1. **System Reset**: Complete removal of all OSTree deployments
|
||||
2. **Clean Slate**: Prepare system for fresh installation
|
||||
3. **Recovery**: Reset system to a clean state when deployments are corrupted
|
||||
4. **Maintenance**: Remove all bootc-managed state
|
||||
|
||||
## Command Structure
|
||||
|
||||
```rust
|
||||
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
|
||||
pub(crate) enum StateOpts {
|
||||
/// Remove all ostree deployments from this system
|
||||
WipeOstree,
|
||||
}
|
||||
```
|
||||
|
||||
## Core Command: wipe-ostree
|
||||
|
||||
### Purpose
|
||||
|
||||
The `wipe-ostree` command completely removes all OSTree deployments from the system, effectively resetting the bootc-managed state to a clean slate.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
bootc state wipe-ostree
|
||||
```
|
||||
|
||||
### Functionality
|
||||
|
||||
- **Complete Removal**: Removes all OSTree deployments from the system
|
||||
- **System Reset**: Resets the system to a state where no bootc deployments exist
|
||||
- **Clean Slate**: Prepares the system for fresh installation
|
||||
- **Recovery**: Can be used to recover from corrupted deployment states
|
||||
|
||||
### Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) async fn wipe_ostree(sysroot: Sysroot) -> Result<()> {
|
||||
tokio::task::spawn_blocking(move || {
|
||||
sysroot
|
||||
.write_deployments(&[], gio::Cancellable::NONE)
|
||||
.context("removing deployments")
|
||||
})
|
||||
.await??;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### Command Routing
|
||||
|
||||
The command is routed through the main CLI dispatcher:
|
||||
|
||||
```rust
|
||||
Opt::State(opts) => match opts {
|
||||
StateOpts::WipeOstree => {
|
||||
let sysroot = ostree::Sysroot::new_default();
|
||||
sysroot.load(gio::Cancellable::NONE)?;
|
||||
crate::deploy::wipe_ostree(sysroot).await?;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
### 1. OSTree Integration
|
||||
|
||||
The `wipe-ostree` command directly interfaces with the OSTree library:
|
||||
|
||||
```rust
|
||||
// Create OSTree sysroot instance
|
||||
let sysroot = ostree::Sysroot::new_default();
|
||||
|
||||
// Load the sysroot
|
||||
sysroot.load(gio::Cancellable::NONE)?;
|
||||
|
||||
// Remove all deployments by writing empty array
|
||||
sysroot.write_deployments(&[], gio::Cancellable::NONE)
|
||||
.context("removing deployments")?;
|
||||
```
|
||||
|
||||
### 2. Asynchronous Execution
|
||||
|
||||
The operation is executed asynchronously to prevent blocking:
|
||||
|
||||
```rust
|
||||
tokio::task::spawn_blocking(move || {
|
||||
// OSTree operations in blocking context
|
||||
sysroot.write_deployments(&[], gio::Cancellable::NONE)
|
||||
.context("removing deployments")
|
||||
}).await??;
|
||||
```
|
||||
|
||||
### 3. Error Handling
|
||||
|
||||
Comprehensive error handling with context:
|
||||
|
||||
```rust
|
||||
#[context("removing deployments")]
|
||||
pub(crate) async fn wipe_ostree(sysroot: Sysroot) -> Result<()> {
|
||||
// Implementation with automatic error context
|
||||
}
|
||||
```
|
||||
|
||||
## System Impact
|
||||
|
||||
### 1. What Gets Removed
|
||||
|
||||
- **All OSTree Deployments**: Every deployment managed by OSTree
|
||||
- **Boot Entries**: All bootloader entries for bootc deployments
|
||||
- **System State**: Complete reset of bootc-managed system state
|
||||
- **Deployment History**: All deployment history and metadata
|
||||
|
||||
### 2. What Remains
|
||||
|
||||
- **Base System**: The underlying operating system remains intact
|
||||
- **User Data**: User data in `/home` and other non-OSTree locations
|
||||
- **System Configuration**: Non-OSTree system configuration
|
||||
- **Installed Packages**: System packages not managed by OSTree
|
||||
|
||||
### 3. System State After Wipe
|
||||
|
||||
After running `wipe-ostree`, the system will be in a state where:
|
||||
|
||||
- No bootc deployments exist
|
||||
- No OSTree-managed content is present
|
||||
- The system may not boot if it was entirely OSTree-based
|
||||
- Fresh installation is required to restore bootc functionality
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. System Recovery
|
||||
|
||||
When the system is in an unrecoverable state:
|
||||
|
||||
```bash
|
||||
# Check current state
|
||||
bootc status
|
||||
|
||||
# If system is corrupted, wipe and reinstall
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Reinstall from scratch
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### 2. Clean Installation
|
||||
|
||||
When preparing for a fresh installation:
|
||||
|
||||
```bash
|
||||
# Wipe existing deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Install new system
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### 3. Development and Testing
|
||||
|
||||
When testing installation procedures:
|
||||
|
||||
```bash
|
||||
# Reset test environment
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Test installation process
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### 4. System Migration
|
||||
|
||||
When migrating to a different bootc setup:
|
||||
|
||||
```bash
|
||||
# Remove old deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Install new configuration
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Privilege Requirements
|
||||
|
||||
The command requires root privileges:
|
||||
|
||||
```rust
|
||||
pub(crate) fn require_root(is_container: bool) -> Result<()> {
|
||||
ensure!(
|
||||
rustix::process::getuid().is_root(),
|
||||
if is_container {
|
||||
"The user inside the container from which you are running this command must be root"
|
||||
} else {
|
||||
"This command must be executed as the root user"
|
||||
}
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Destructive Operation
|
||||
|
||||
This is a destructive operation that cannot be undone:
|
||||
|
||||
- **No Undo**: Once executed, deployments cannot be restored
|
||||
- **System Impact**: May render system unbootable
|
||||
- **Data Loss**: All bootc-managed state is lost
|
||||
|
||||
### 3. Safety Checks
|
||||
|
||||
The command should be used with extreme caution:
|
||||
|
||||
- **Backup Required**: Always backup important data before execution
|
||||
- **System Verification**: Ensure system can be reinstalled
|
||||
- **Recovery Plan**: Have a recovery plan ready
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Common Error Scenarios
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
# Error: Permission denied
|
||||
# Solution: Run as root
|
||||
sudo bootc state wipe-ostree
|
||||
```
|
||||
|
||||
#### OSTree Not Available
|
||||
```bash
|
||||
# Error: OSTree not found
|
||||
# Solution: Install OSTree
|
||||
apt install ostree
|
||||
```
|
||||
|
||||
#### System Not OSTree-Based
|
||||
```bash
|
||||
# Error: No OSTree deployments found
|
||||
# Solution: Verify system is OSTree-based
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
### 2. Error Recovery
|
||||
|
||||
If the command fails:
|
||||
|
||||
1. **Check Logs**: Review system logs for details
|
||||
2. **Verify System**: Ensure system is OSTree-based
|
||||
3. **Check Permissions**: Verify root privileges
|
||||
4. **Manual Cleanup**: May require manual OSTree cleanup
|
||||
|
||||
## Integration with Other Commands
|
||||
|
||||
### 1. Status Command
|
||||
|
||||
Check system state before and after:
|
||||
|
||||
```bash
|
||||
# Before wipe
|
||||
bootc status
|
||||
|
||||
# Wipe deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# After wipe (should show no deployments)
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 2. Install Command
|
||||
|
||||
Typically followed by fresh installation:
|
||||
|
||||
```bash
|
||||
# Wipe existing deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Install fresh system
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### 3. OSTree Commands
|
||||
|
||||
Can be used with OSTree commands:
|
||||
|
||||
```bash
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Wipe deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Verify wipe
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### 1. Execution Time
|
||||
|
||||
- **Fast**: Operation completes quickly
|
||||
- **Atomic**: Single atomic operation
|
||||
- **Efficient**: Minimal resource usage
|
||||
|
||||
### 2. Resource Usage
|
||||
|
||||
- **Low CPU**: Minimal CPU usage
|
||||
- **Low Memory**: Minimal memory usage
|
||||
- **Disk I/O**: Only metadata operations
|
||||
|
||||
### 3. System Impact
|
||||
|
||||
- **Immediate**: Effect is immediate
|
||||
- **Permanent**: Cannot be undone
|
||||
- **Complete**: Removes all deployments
|
||||
|
||||
## Testing and Validation
|
||||
|
||||
### 1. Unit Tests
|
||||
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_wipe_ostree() {
|
||||
let temp_dir = tempfile::tempdir().unwrap();
|
||||
let sysroot = create_test_sysroot(temp_dir.path()).unwrap();
|
||||
|
||||
// Add test deployments
|
||||
add_test_deployments(&sysroot).await.unwrap();
|
||||
|
||||
// Verify deployments exist
|
||||
let deployments = sysroot.deployments();
|
||||
assert!(!deployments.is_empty());
|
||||
|
||||
// Wipe deployments
|
||||
wipe_ostree(sysroot).await.unwrap();
|
||||
|
||||
// Verify deployments are gone
|
||||
let deployments = sysroot.deployments();
|
||||
assert!(deployments.is_empty());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Integration Tests
|
||||
|
||||
```rust
|
||||
#[tokio::test]
|
||||
async fn test_wipe_ostree_integration() {
|
||||
// Setup test environment
|
||||
let test_env = TestEnvironment::new().await.unwrap();
|
||||
|
||||
// Install test system
|
||||
test_env.install_test_system().await.unwrap();
|
||||
|
||||
// Verify system is installed
|
||||
let status = test_env.run_command("bootc", &["status"]).await.unwrap();
|
||||
assert!(status.contains("booted"));
|
||||
|
||||
// Wipe deployments
|
||||
test_env.run_command("bootc", &["state", "wipe-ostree"]).await.unwrap();
|
||||
|
||||
// Verify deployments are gone
|
||||
let status = test_env.run_command("bootc", &["status"]).await.unwrap();
|
||||
assert!(status.contains("No deployments found"));
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Usage Guidelines
|
||||
|
||||
- **Backup First**: Always backup important data
|
||||
- **Verify System**: Ensure system is OSTree-based
|
||||
- **Plan Recovery**: Have recovery plan ready
|
||||
- **Test First**: Test in non-production environment
|
||||
|
||||
### 2. Safety Measures
|
||||
|
||||
- **Confirmation**: Consider adding confirmation prompt
|
||||
- **Logging**: Log all wipe operations
|
||||
- **Monitoring**: Monitor system after wipe
|
||||
- **Documentation**: Document wipe procedures
|
||||
|
||||
### 3. Recovery Procedures
|
||||
|
||||
- **Fresh Install**: Plan for fresh installation
|
||||
- **Data Recovery**: Ensure data is backed up
|
||||
- **System Restore**: Have system restore plan
|
||||
- **Testing**: Test recovery procedures
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Additional State Commands
|
||||
|
||||
Potential future state commands:
|
||||
|
||||
```rust
|
||||
pub(crate) enum StateOpts {
|
||||
WipeOstree,
|
||||
ResetConfig, // Reset configuration
|
||||
ClearCache, // Clear system cache
|
||||
ResetSecrets, // Reset secrets
|
||||
WipeComposefs, // Wipe composefs data
|
||||
ResetBootloader, // Reset bootloader
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Safety Features
|
||||
|
||||
Enhanced safety features:
|
||||
|
||||
```rust
|
||||
pub(crate) struct WipeOptions {
|
||||
pub confirm: bool,
|
||||
pub backup: bool,
|
||||
pub dry_run: bool,
|
||||
pub force: bool,
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Recovery Tools
|
||||
|
||||
Recovery and restoration tools:
|
||||
|
||||
```rust
|
||||
pub(crate) enum RecoveryOpts {
|
||||
RestoreFromBackup { backup_path: PathBuf },
|
||||
RestoreFromImage { image: String },
|
||||
RestoreFromSnapshot { snapshot: String },
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### Command Not Found
|
||||
```bash
|
||||
# Error: bootc state: command not found
|
||||
# Solution: Ensure bootc is installed and in PATH
|
||||
which bootc
|
||||
```
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
# Error: Permission denied
|
||||
# Solution: Run as root
|
||||
sudo bootc state wipe-ostree
|
||||
```
|
||||
|
||||
#### OSTree Error
|
||||
```bash
|
||||
# Error: OSTree operation failed
|
||||
# Solution: Check OSTree installation and system state
|
||||
ostree --version
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
### 2. Debug Information
|
||||
|
||||
Enable debug logging:
|
||||
|
||||
```bash
|
||||
# Set debug log level
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Run command with debug output
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Check debug logs
|
||||
journalctl -u bootc-* --since "1 hour ago" | grep DEBUG
|
||||
```
|
||||
|
||||
### 3. System Verification
|
||||
|
||||
Verify system state:
|
||||
|
||||
```bash
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check bootc status
|
||||
bootc status
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-* --since "1 hour ago"
|
||||
```
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc state system's functionality, implementation, and usage patterns.
|
||||
969
status/bootc-status-external-commands.md
Normal file
969
status/bootc-status-external-commands.md
Normal file
|
|
@ -0,0 +1,969 @@
|
|||
# bootc status - 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 status` system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc status into larger systems.
|
||||
|
||||
## Core System Commands
|
||||
|
||||
### 1. bootc Commands
|
||||
|
||||
#### bootc status
|
||||
**Purpose**: Display system status and deployment information
|
||||
**Usage**: `bootc status [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment information
|
||||
- `systemd` - For service status
|
||||
- `jq` - For JSON parsing (optional)
|
||||
|
||||
```bash
|
||||
# Show current system status
|
||||
bootc status
|
||||
|
||||
# Show status in JSON format
|
||||
bootc status --format=json
|
||||
|
||||
# Show detailed status with verbose output
|
||||
bootc status --verbose
|
||||
|
||||
# Show only booted deployment status
|
||||
bootc status --booted
|
||||
|
||||
# Show status in YAML format
|
||||
bootc status --format=yaml
|
||||
```
|
||||
|
||||
#### bootc upgrade
|
||||
**Purpose**: Update current image to newer version
|
||||
**Usage**: `bootc upgrade [OPTIONS...]`
|
||||
**Integration**: Used to check status before/after upgrades
|
||||
|
||||
```bash
|
||||
# Check status before upgrade
|
||||
bootc status
|
||||
bootc upgrade --apply
|
||||
bootc status
|
||||
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
#### bootc switch
|
||||
**Purpose**: Switch to different container image reference
|
||||
**Usage**: `bootc switch [OPTIONS...] <TARGET>`
|
||||
**Integration**: Used to check status before/after switches
|
||||
|
||||
```bash
|
||||
# Check status before switch
|
||||
bootc status
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
bootc status
|
||||
```
|
||||
|
||||
#### bootc rollback
|
||||
**Purpose**: Rollback to previous deployment
|
||||
**Usage**: `bootc rollback [OPTIONS...]`
|
||||
**Integration**: Used to check status before/after rollbacks
|
||||
|
||||
```bash
|
||||
# Check status before rollback
|
||||
bootc status
|
||||
bootc rollback
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
# Check with verbose output
|
||||
ostree admin status --verbose
|
||||
```
|
||||
|
||||
#### 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 internally by bootc 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
|
||||
```
|
||||
|
||||
#### ostree refs
|
||||
**Purpose**: List OSTree references
|
||||
**Usage**: `ostree refs [OPTIONS...]`
|
||||
**Integration**: Used for reference management
|
||||
|
||||
```bash
|
||||
# List all references
|
||||
ostree refs
|
||||
|
||||
# List references for specific remote
|
||||
ostree refs --remote=quay.io
|
||||
|
||||
# List references with details
|
||||
ostree refs --list
|
||||
```
|
||||
|
||||
### 3. System Management Commands
|
||||
|
||||
#### systemctl
|
||||
**Purpose**: Control systemd services and units
|
||||
**Usage**: `systemctl [COMMAND] [UNIT...]`
|
||||
**Integration**: Used for service management and status checking
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-fetch-apply-updates.service
|
||||
|
||||
# Start service
|
||||
systemctl start bootc-fetch-apply-updates.service
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-fetch-apply-updates.service
|
||||
|
||||
# Restart service
|
||||
systemctl restart bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### reboot
|
||||
**Purpose**: Reboot the system
|
||||
**Usage**: `reboot [OPTIONS...]`
|
||||
**Integration**: Used for system restart after status changes
|
||||
|
||||
```bash
|
||||
# Reboot system
|
||||
reboot
|
||||
|
||||
# Reboot with specific delay
|
||||
reboot +5
|
||||
|
||||
# Reboot with message
|
||||
reboot "Applying bootc changes"
|
||||
```
|
||||
|
||||
#### shutdown
|
||||
**Purpose**: Shutdown the system
|
||||
**Usage**: `shutdown [OPTIONS...]`
|
||||
**Integration**: Used for controlled shutdown
|
||||
|
||||
```bash
|
||||
# Shutdown system
|
||||
shutdown -h now
|
||||
|
||||
# Shutdown with delay
|
||||
shutdown -h +5
|
||||
|
||||
# Shutdown with message
|
||||
shutdown -h now "Applying bootc changes"
|
||||
```
|
||||
|
||||
## Data Processing Commands
|
||||
|
||||
### 1. JSON Processing
|
||||
|
||||
#### jq
|
||||
**Purpose**: JSON processor and query tool
|
||||
**Usage**: `jq [OPTIONS...] [FILTER] [FILE...]`
|
||||
**Integration**: Used for parsing and processing JSON output
|
||||
|
||||
```bash
|
||||
# Parse JSON output
|
||||
bootc status --format=json | jq '.status.booted'
|
||||
|
||||
# Check if system is bootc compatible
|
||||
bootc status --format=json | jq '.status.booted != null'
|
||||
|
||||
# Get current image version
|
||||
bootc status --format=json | jq -r '.status.booted.image.version // "unknown"'
|
||||
|
||||
# Check rollback status
|
||||
bootc status --format=json | jq '.status.rollbackQueued'
|
||||
|
||||
# Get image digest
|
||||
bootc status --format=json | jq -r '.status.booted.image.imageDigest'
|
||||
|
||||
# List all deployments
|
||||
bootc status --format=json | jq '.status | keys'
|
||||
```
|
||||
|
||||
#### yq
|
||||
**Purpose**: YAML processor and query tool
|
||||
**Usage**: `yq [OPTIONS...] [EXPRESSION] [FILE...]`
|
||||
**Integration**: Used for parsing and processing YAML output
|
||||
|
||||
```bash
|
||||
# Parse YAML output
|
||||
bootc status --format=yaml | yq '.status.booted'
|
||||
|
||||
# Get current image version
|
||||
bootc status --format=yaml | yq '.status.booted.image.version'
|
||||
|
||||
# Check rollback status
|
||||
bootc status --format=yaml | yq '.status.rollbackQueued'
|
||||
|
||||
# Get image digest
|
||||
bootc status --format=yaml | yq '.status.booted.image.imageDigest'
|
||||
```
|
||||
|
||||
### 2. Text Processing
|
||||
|
||||
#### grep
|
||||
**Purpose**: Search text patterns
|
||||
**Usage**: `grep [OPTIONS...] PATTERN [FILE...]`
|
||||
**Integration**: Used for filtering and searching output
|
||||
|
||||
```bash
|
||||
# Search for specific image
|
||||
bootc status | grep "quay.io/myorg"
|
||||
|
||||
# Search for rollback status
|
||||
bootc status | grep "Rollback Queued"
|
||||
|
||||
# Search for version information
|
||||
bootc status | grep "Version:"
|
||||
```
|
||||
|
||||
#### awk
|
||||
**Purpose**: Text processing and data extraction
|
||||
**Usage**: `awk [OPTIONS...] 'PROGRAM' [FILE...]`
|
||||
**Integration**: Used for extracting specific fields
|
||||
|
||||
```bash
|
||||
# Extract image name
|
||||
bootc status | awk '/Image:/ {print $2}'
|
||||
|
||||
# Extract version
|
||||
bootc status | awk '/Version:/ {print $2}'
|
||||
|
||||
# Extract digest
|
||||
bootc status | awk '/Digest:/ {print $2}'
|
||||
```
|
||||
|
||||
#### sed
|
||||
**Purpose**: Stream editor for filtering and transforming text
|
||||
**Usage**: `sed [OPTIONS...] SCRIPT [FILE...]`
|
||||
**Integration**: Used for text transformation
|
||||
|
||||
```bash
|
||||
# Remove leading whitespace
|
||||
bootc status | sed 's/^[[:space:]]*//'
|
||||
|
||||
# Extract specific lines
|
||||
bootc status | sed -n '/Image:/p'
|
||||
|
||||
# Replace text
|
||||
bootc status | sed 's/quay.io/myorg/quay.io/otherorg/g'
|
||||
```
|
||||
|
||||
### 3. Data Formatting
|
||||
|
||||
#### column
|
||||
**Purpose**: Format text into columns
|
||||
**Usage**: `column [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for formatting output
|
||||
|
||||
```bash
|
||||
# Format status output in columns
|
||||
bootc status | column -t
|
||||
|
||||
# Format with specific separator
|
||||
bootc status | column -s ':' -t
|
||||
```
|
||||
|
||||
#### sort
|
||||
**Purpose**: Sort lines of text
|
||||
**Usage**: `sort [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for sorting output
|
||||
|
||||
```bash
|
||||
# Sort status output
|
||||
bootc status | sort
|
||||
|
||||
# Sort by specific field
|
||||
bootc status | sort -k2
|
||||
```
|
||||
|
||||
#### uniq
|
||||
**Purpose**: Remove duplicate lines
|
||||
**Usage**: `uniq [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for removing duplicates
|
||||
|
||||
```bash
|
||||
# Remove duplicate lines
|
||||
bootc status | uniq
|
||||
|
||||
# Count unique lines
|
||||
bootc status | uniq -c
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
# Check status-related logs
|
||||
journalctl -u bootc-fetch-apply-updates.service | grep status
|
||||
```
|
||||
|
||||
#### 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 /etc/bootc/config.yaml
|
||||
|
||||
# Display first bytes
|
||||
head -c 100 /etc/bootc/config.yaml
|
||||
```
|
||||
|
||||
## Network Commands
|
||||
|
||||
### 1. HTTP Clients
|
||||
|
||||
#### curl
|
||||
**Purpose**: HTTP client for registry communication
|
||||
**Usage**: `curl [OPTIONS...] URL`
|
||||
**Integration**: Used for registry API calls and authentication
|
||||
|
||||
```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/v2.0
|
||||
|
||||
# Authenticate with registry
|
||||
curl -u username:password https://quay.io/v2/token
|
||||
```
|
||||
|
||||
#### 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/v2.0
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
### 3. Network Troubleshooting
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
#### traceroute
|
||||
**Purpose**: Trace network path
|
||||
**Usage**: `traceroute [OPTIONS...] HOST`
|
||||
**Integration**: Used for network path analysis
|
||||
|
||||
```bash
|
||||
# Trace path to registry
|
||||
traceroute quay.io
|
||||
|
||||
# Trace with specific options
|
||||
traceroute -n quay.io
|
||||
```
|
||||
|
||||
## Container Runtime Commands
|
||||
|
||||
### 1. Podman Commands
|
||||
|
||||
#### podman pull
|
||||
**Purpose**: Pull container images from registry
|
||||
**Usage**: `podman pull [OPTIONS...] IMAGE`
|
||||
**Integration**: Used by bootc for downloading images
|
||||
|
||||
```bash
|
||||
# Pull image from registry
|
||||
podman pull quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Pull with authentication
|
||||
podman pull --creds=username:password quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Pull specific tag
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
#### 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:v2.0
|
||||
|
||||
# Inspect specific configuration
|
||||
podman inspect --format='{{.Config.Labels}}' quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Inspect manifest
|
||||
podman inspect --format='{{.Manifest}}' quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### podman images
|
||||
**Purpose**: List container images
|
||||
**Usage**: `podman images [OPTIONS...]`
|
||||
**Integration**: Used for image management
|
||||
|
||||
```bash
|
||||
# List all images
|
||||
podman images
|
||||
|
||||
# List images with specific format
|
||||
podman images --format "table {{.Repository}} {{.Tag}} {{.ID}}"
|
||||
|
||||
# List images with filters
|
||||
podman images --filter "reference=quay.io/myorg/*"
|
||||
```
|
||||
|
||||
### 2. Docker Commands (Alternative)
|
||||
|
||||
#### docker
|
||||
**Purpose**: Alternative container runtime
|
||||
**Usage**: `docker [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Alternative to podman
|
||||
|
||||
```bash
|
||||
# List containers
|
||||
docker ps -a
|
||||
|
||||
# List images
|
||||
docker images
|
||||
|
||||
# Inspect image
|
||||
docker inspect quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
## 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 /etc/bootc/config.yaml
|
||||
|
||||
# Display with line numbers
|
||||
cat -n /etc/bootc/config.yaml
|
||||
|
||||
# Display non-printing characters
|
||||
cat -v /etc/bootc/config.yaml
|
||||
```
|
||||
|
||||
#### cp
|
||||
**Purpose**: Copy files
|
||||
**Usage**: `cp [OPTIONS...] SOURCE DEST`
|
||||
**Integration**: Used for backing up configuration files
|
||||
|
||||
```bash
|
||||
# Copy file
|
||||
cp /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
|
||||
|
||||
# Copy with preserve attributes
|
||||
cp -p /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
|
||||
|
||||
# Copy recursively
|
||||
cp -r /etc/bootc/ /etc/bootc.backup/
|
||||
```
|
||||
|
||||
#### mv
|
||||
**Purpose**: Move or rename files
|
||||
**Usage**: `mv [OPTIONS...] SOURCE DEST`
|
||||
**Integration**: Used for renaming configuration files
|
||||
|
||||
```bash
|
||||
# Rename file
|
||||
mv /etc/bootc/config.yaml /etc/bootc/config.yaml.old
|
||||
|
||||
# Move file
|
||||
mv /etc/bootc/config.yaml /backup/config.yaml
|
||||
```
|
||||
|
||||
#### rm
|
||||
**Purpose**: Remove files
|
||||
**Usage**: `rm [OPTIONS...] FILE...`
|
||||
**Integration**: Used for cleaning up temporary files
|
||||
|
||||
```bash
|
||||
# Remove file
|
||||
rm /etc/bootc/config.yaml
|
||||
|
||||
# Remove with confirmation
|
||||
rm -i /etc/bootc/config.yaml
|
||||
|
||||
# Remove recursively
|
||||
rm -r /etc/bootc/
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## System Information Commands
|
||||
|
||||
### 1. 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
|
||||
```
|
||||
|
||||
### 2. Hardware Information
|
||||
|
||||
#### lscpu
|
||||
**Purpose**: Display CPU information
|
||||
**Usage**: `lscpu [OPTIONS...]`
|
||||
**Integration**: Used for system resource analysis
|
||||
|
||||
```bash
|
||||
# Display CPU information
|
||||
lscpu
|
||||
|
||||
# Display in specific format
|
||||
lscpu --extended
|
||||
```
|
||||
|
||||
#### lsblk
|
||||
**Purpose**: List block devices
|
||||
**Usage**: `lsblk [OPTIONS...]`
|
||||
**Integration**: Used for storage device identification
|
||||
|
||||
```bash
|
||||
# List all block devices
|
||||
lsblk
|
||||
|
||||
# List with filesystem information
|
||||
lsblk -f
|
||||
|
||||
# List specific device
|
||||
lsblk /dev/sda
|
||||
```
|
||||
|
||||
## Automation and Scripting Commands
|
||||
|
||||
### 1. Shell Scripting
|
||||
|
||||
#### bash
|
||||
**Purpose**: Bourne Again Shell
|
||||
**Usage**: `bash [OPTIONS...] [FILE]`
|
||||
**Integration**: Used for automation scripts
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Check if system is bootc compatible
|
||||
if bootc status --format=json | jq -e '.status.booted != null' > /dev/null; then
|
||||
echo "System is bootc compatible"
|
||||
else
|
||||
echo "System is not bootc compatible"
|
||||
fi
|
||||
```
|
||||
|
||||
#### sh
|
||||
**Purpose**: POSIX shell
|
||||
**Usage**: `sh [OPTIONS...] [FILE]`
|
||||
**Integration**: Used for portable scripts
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
# Check rollback status
|
||||
if bootc status --format=json | jq -r '.status.rollbackQueued' | grep -q true; then
|
||||
echo "Rollback is queued"
|
||||
fi
|
||||
```
|
||||
|
||||
### 2. Process Control
|
||||
|
||||
#### ps
|
||||
**Purpose**: Display running processes
|
||||
**Usage**: `ps [OPTIONS...]`
|
||||
**Integration**: Used for process monitoring
|
||||
|
||||
```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 process identification
|
||||
|
||||
```bash
|
||||
# Find bootc processes
|
||||
pgrep bootc
|
||||
|
||||
# Find with full command line
|
||||
pgrep -f bootc
|
||||
|
||||
# Find with specific user
|
||||
pgrep -u root bootc
|
||||
```
|
||||
|
||||
#### pkill
|
||||
**Purpose**: Kill processes by name
|
||||
**Usage**: `pkill [OPTIONS...] PATTERN`
|
||||
**Integration**: Used for process termination
|
||||
|
||||
```bash
|
||||
# Kill bootc processes
|
||||
pkill bootc
|
||||
|
||||
# Kill with signal
|
||||
pkill -9 bootc
|
||||
|
||||
# Kill with specific user
|
||||
pkill -u root bootc
|
||||
```
|
||||
|
||||
## 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 /etc/bootc/config.yaml
|
||||
|
||||
# Commit changes
|
||||
git commit -m "Update configuration"
|
||||
|
||||
# Check status
|
||||
git status
|
||||
```
|
||||
|
||||
This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc status system.
|
||||
459
status/bootc-status-flowchart.md
Normal file
459
status/bootc-status-flowchart.md
Normal file
|
|
@ -0,0 +1,459 @@
|
|||
# bootc status - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc status` process flow, showing the decision points, operations, and data structures involved in displaying system status information.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc status │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Validate Format Version │
|
||||
│ │
|
||||
│ • Check format version (0, 1 supported) │
|
||||
│ • Error if unsupported version │
|
||||
│ • Default to version 1 │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check OSTree Boot Status │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ ostree_booted()? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ No │ │ Yes │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Return ││ │ │ Get System Status ││ │
|
||||
│ │ │ Default ││ │ │ ││ │
|
||||
│ │ │ Empty ││ │ │ • Get storage interface ││ │
|
||||
│ │ │ Status ││ │ │ • Get OSTree repository ││ │
|
||||
│ │ └─────────────┘│ │ │ • Get booted deployment ││ │
|
||||
│ │ │ │ │ • Call get_status() ││ │
|
||||
│ │ ┌─────────────┐│ │ └─────────────────────────────────┘│ │
|
||||
│ │ │ Skip to ││ │ │ │
|
||||
│ │ │ Output ││ │ │ │
|
||||
│ │ └─────────────┘│ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Filter to Booted Deployment │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --booted specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Filter to ││ │ │ Keep All Deployments ││ │
|
||||
│ │ │ Booted ││ │ │ ││ │
|
||||
│ │ │ Slot Only ││ │ │ • Include all deployment info ││ │
|
||||
│ │ │ ││ │ │ • Show staged, booted, rollback││ │
|
||||
│ │ └─────────────┘│ │ │ ││ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Output Format │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Format specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use ││ │ │ Auto-detect Format ││ │
|
||||
│ │ │ Specified ││ │ │ ││ │
|
||||
│ │ │ Format ││ │ │ • Check --json flag ││ │
|
||||
│ │ │ • JSON ││ │ │ • Check if terminal ││ │
|
||||
│ │ │ • YAML ││ │ │ • Default to YAML ││ │
|
||||
│ │ │ • Human ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Output in Requested Format │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Format Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ JSON │ │ YAML │ │ Human Readable│ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Serialize ││ │ │ Serialize ││ │ │ Format for ││ │
|
||||
│ │ │ to JSON ││ │ │ to YAML ││ │ │ human ││ │
|
||||
│ │ │ • Canonical ││ │ │ • Standard ││ │ │ reading ││ │
|
||||
│ │ │ format ││ │ │ format ││ │ │ • Include ││ │
|
||||
│ │ │ • Machine ││ │ │ • Machine ││ │ │ verbose ││ │
|
||||
│ │ │ readable ││ │ │ readable ││ │ │ info if ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ │ requested ││ │
|
||||
│ └─────────────────┘ └─────────────────┘ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Status information displayed successfully │
|
||||
│ • Format appropriate for use case │
|
||||
│ • All deployment information included │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Status Gathering Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Core Status Gathering │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Get Stateroot Name │
|
||||
│ │
|
||||
│ • Extract stateroot from booted deployment │
|
||||
│ • Use for filtering related deployments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Partition Deployments │
|
||||
│ │
|
||||
│ • Get all deployments from sysroot │
|
||||
│ • Separate related deployments from others │
|
||||
│ • Filter by stateroot name │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Find Staged Deployment │
|
||||
│ │
|
||||
│ • Search for deployment marked as staged │
|
||||
│ • Remove from related deployments list │
|
||||
│ • Store for later processing │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Filter Booted Deployment │
|
||||
│ │
|
||||
│ • Remove booted deployment from related list │
|
||||
│ • Keep for separate processing │
|
||||
│ • Ensure no duplicates │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Get Rollback Deployment │
|
||||
│ │
|
||||
│ • Pop first deployment from related list │
|
||||
│ • This becomes rollback deployment │
|
||||
│ • Remaining deployments become "other" │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Rollback Status │
|
||||
│ │
|
||||
│ • Compare rollback and booted deployment indices │
|
||||
│ • Set rollback_queued flag │
|
||||
│ • Determine boot order state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Boot Entries │
|
||||
│ │
|
||||
│ • Process staged deployment │
|
||||
│ • Process booted deployment │
|
||||
│ • Process rollback deployment │
|
||||
│ • Process other deployments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Extract Image Information │
|
||||
│ │
|
||||
│ • Parse OCI image configuration │
|
||||
│ • Extract image metadata │
|
||||
│ • Create ImageStatus structures │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Host Specification │
|
||||
│ │
|
||||
│ • Determine image reference │
|
||||
│ • Set boot order │
|
||||
│ • Create HostSpec structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Host Type │
|
||||
│ │
|
||||
│ • Check if booted deployment has image │
|
||||
│ • Set HostType::BootcHost if container-based │
|
||||
│ • Set to None if not container-based │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Host Status │
|
||||
│ │
|
||||
│ • Combine all deployment information │
|
||||
│ • Set rollback_queued flag │
|
||||
│ • Set host type │
|
||||
│ • Create HostStatus structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Complete status information gathered │
|
||||
│ • All deployments processed │
|
||||
│ • Image information extracted │
|
||||
│ • Ready for output formatting │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Boot Entry Creation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Boot Entry Creation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Extract Deployment Info │
|
||||
│ │
|
||||
│ • Get deployment checksum │
|
||||
│ • Get deployment osname │
|
||||
│ • Create DeploymentInfo structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check for Image Reference │
|
||||
│ │
|
||||
│ • Parse deployment origin │
|
||||
│ • Look for refspec in origin │
|
||||
│ • Parse OSTree image reference │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Query Image Commit │
|
||||
│ │
|
||||
│ • Query OSTree repository for image commit │
|
||||
│ • Get cached update information │
|
||||
│ • Extract image configuration │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Image Status │
|
||||
│ │
|
||||
│ • Parse OCI image configuration │
|
||||
│ • Extract labels and metadata │
|
||||
│ • Create ImageStatus structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Boot Entry │
|
||||
│ │
|
||||
│ • Combine deployment info and image status │
|
||||
│ • Create BootEntry structure │
|
||||
│ • Return complete boot entry │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Image Status Creation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Image Status Creation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Extract Image Labels │
|
||||
│ │
|
||||
│ • Get labels from image configuration │
|
||||
│ • Look for version information │
|
||||
│ • Look for timestamp information │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Timestamp │
|
||||
│ │
|
||||
│ • Look for ANNOTATION_CREATED label │
|
||||
│ • Parse RFC3339 timestamp │
|
||||
│ • Convert to UTC timezone │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Extract Architecture │
|
||||
│ │
|
||||
│ • Get architecture from image configuration │
|
||||
│ • Default to "unknown" if not found │
|
||||
│ • Convert to string │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Image Status │
|
||||
│ │
|
||||
│ • Combine image reference and metadata │
|
||||
│ • Set version, timestamp, digest, architecture │
|
||||
│ • Create ImageStatus structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Format Selection Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Format Selection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Format Option │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --format specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use ││ │ │ Check Legacy Options ││ │
|
||||
│ │ │ Specified ││ │ │ ││ │
|
||||
│ │ │ Format ││ │ │ • Check --json flag ││ │
|
||||
│ │ │ • JSON ││ │ │ • Check if terminal ││ │
|
||||
│ │ │ • YAML ││ │ │ • Default to YAML ││ │
|
||||
│ │ │ • Human ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Legacy Options │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --json specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use JSON ││ │ │ Check Terminal ││ │
|
||||
│ │ │ Format ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ │ • Check if stdout is terminal ││ │
|
||||
│ │ │ │ │ • Use Human Readable if yes ││ │
|
||||
│ │ │ │ │ • Use YAML if no ││ │
|
||||
│ │ │ │ │ ││ │
|
||||
│ │ │ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Terminal Status │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ stdout.is_terminal()? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use Human ││ │ │ Use YAML Format ││ │
|
||||
│ │ │ Readable ││ │ │ ││ │
|
||||
│ │ │ Format ││ │ │ • Machine readable ││ │
|
||||
│ │ │ ││ │ │ • Programmatic parsing ││ │
|
||||
│ │ │ • Interactive││ │ │ • Standard format ││ │
|
||||
│ │ │ use ││ │ │ ││ │
|
||||
│ │ │ • Human ││ │ │ ││ │
|
||||
│ │ │ friendly ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Format │ │ System │ │ Deployment │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Unsupported │ │ • Not OSTree │ │ • No deployments│ │
|
||||
│ │ format │ │ booted │ │ found │ │
|
||||
│ │ version │ │ • Storage │ │ • Invalid │ │
|
||||
│ │ • Invalid │ │ access │ │ deployment │ │
|
||||
│ │ format │ │ failed │ │ structure │ │
|
||||
│ │ • JSON/YAML │ │ • OSTree │ │ • Image │ │
|
||||
│ │ parsing │ │ repository │ │ parsing │ │
|
||||
│ │ failed │ │ error │ │ failed │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up any partial state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc status process, showing all decision points, operations, and data structures involved in displaying system status information.
|
||||
832
status/bootc-status-technical-guide.md
Normal file
832
status/bootc-status-technical-guide.md
Normal file
|
|
@ -0,0 +1,832 @@
|
|||
# bootc status - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc status` is a command for displaying the current state of a bootc-managed system. It provides comprehensive information about deployments, boot order, image references, and system configuration. The command supports multiple output formats and can be used both interactively and programmatically.
|
||||
|
||||
## Purpose
|
||||
|
||||
The status command serves several critical functions:
|
||||
|
||||
1. **System State Display**: Show current bootc system state
|
||||
2. **Deployment Information**: Display staged, booted, and rollback deployments
|
||||
3. **Image References**: Show container image information and metadata
|
||||
4. **Boot Order Status**: Indicate current boot order configuration
|
||||
5. **Programmatic Access**: Provide structured data for automation
|
||||
6. **Troubleshooting**: Help diagnose system issues
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc status [OPTIONS...]
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Show current system status
|
||||
bootc status
|
||||
|
||||
# Show status in JSON format
|
||||
bootc status --format=json
|
||||
|
||||
# Show detailed status with verbose output
|
||||
bootc status --verbose
|
||||
|
||||
# Show only booted deployment status
|
||||
bootc status --booted
|
||||
|
||||
# Show status in YAML format
|
||||
bootc status --format=yaml
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
| Option | Description | Default | Required |
|
||||
|--------|-------------|---------|----------|
|
||||
| `--format` | Output format (humanreadable, yaml, json) | `auto` | No |
|
||||
| `--format-version` | Format version (0, 1) | `1` | No |
|
||||
| `--booted` | Only display booted deployment | `false` | No |
|
||||
| `--verbose`, `-v` | Include additional fields | `false` | No |
|
||||
| `--json` | Output in JSON format (deprecated) | `false` | No |
|
||||
|
||||
### Output Formats
|
||||
|
||||
| Format | Description | Use Case |
|
||||
|--------|-------------|----------|
|
||||
| `humanreadable` | Human-friendly text output | Interactive use |
|
||||
| `yaml` | YAML-formatted output | Programmatic parsing |
|
||||
| `json` | JSON-formatted output | Programmatic parsing |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 1. Status Command Structure
|
||||
|
||||
```rust
|
||||
pub(crate) struct StatusOpts {
|
||||
pub(crate) json: bool, // JSON output (deprecated)
|
||||
pub(crate) format: Option<OutputFormat>, // Output format
|
||||
pub(crate) format_version: Option<u32>, // Format version
|
||||
pub(crate) booted: bool, // Only booted deployment
|
||||
pub(crate) verbose: bool, // Verbose output
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Status Process Flow
|
||||
|
||||
```rust
|
||||
pub(crate) async fn status(opts: StatusOpts) -> Result<()> {
|
||||
// 1. Validate format version
|
||||
match opts.format_version.unwrap_or_default() {
|
||||
0 | 1 => {} // Both 0 and 1 mean "v1"
|
||||
o => anyhow::bail!("Unsupported format version: {o}"),
|
||||
};
|
||||
|
||||
// 2. Get system status
|
||||
let mut host = if !ostree_booted()? {
|
||||
Default::default()
|
||||
} else {
|
||||
let sysroot = super::cli::get_storage().await?;
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let booted_deployment = ostree.booted_deployment();
|
||||
let (_deployments, host) = get_status(&ostree, booted_deployment.as_ref())?;
|
||||
host
|
||||
};
|
||||
|
||||
// 3. Filter to booted deployment if requested
|
||||
if opts.booted {
|
||||
host.filter_to_slot(Slot::Booted);
|
||||
}
|
||||
|
||||
// 4. Determine output format
|
||||
let out = std::io::stdout();
|
||||
let mut out = out.lock();
|
||||
let legacy_opt = if opts.json {
|
||||
OutputFormat::Json
|
||||
} else if std::io::stdout().is_terminal() {
|
||||
OutputFormat::HumanReadable
|
||||
} else {
|
||||
OutputFormat::Yaml
|
||||
};
|
||||
let format = opts.format.unwrap_or(legacy_opt);
|
||||
|
||||
// 5. Output in requested format
|
||||
match format {
|
||||
OutputFormat::Json => host.to_canon_json_writer(&mut out),
|
||||
OutputFormat::Yaml => serde_yaml::to_writer(&mut out, &host),
|
||||
OutputFormat::HumanReadable => {
|
||||
human_readable_output(&mut out, &host, opts.verbose)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Core Status Gathering
|
||||
|
||||
```rust
|
||||
pub(crate) fn get_status(
|
||||
sysroot: &SysrootLock,
|
||||
booted_deployment: Option<&ostree::Deployment>,
|
||||
) -> Result<(Deployments, Host)> {
|
||||
// 1. Get stateroot name
|
||||
let stateroot = booted_deployment.as_ref().map(|d| d.osname());
|
||||
|
||||
// 2. Partition deployments
|
||||
let (mut related_deployments, other_deployments) = sysroot
|
||||
.deployments()
|
||||
.into_iter()
|
||||
.partition::<VecDeque<_>, _>(|d| Some(d.osname()) == stateroot);
|
||||
|
||||
// 3. Find staged deployment
|
||||
let staged = related_deployments
|
||||
.iter()
|
||||
.position(|d| d.is_staged())
|
||||
.map(|i| related_deployments.remove(i).unwrap());
|
||||
|
||||
// 4. Filter out booted deployment
|
||||
if let Some(booted) = booted_deployment.as_ref() {
|
||||
related_deployments.retain(|f| !f.equal(booted));
|
||||
}
|
||||
|
||||
// 5. Get rollback deployment
|
||||
let rollback = related_deployments.pop_front();
|
||||
|
||||
// 6. Determine rollback queued status
|
||||
let rollback_queued = match (booted_deployment.as_ref(), rollback.as_ref()) {
|
||||
(Some(booted), Some(rollback)) => rollback.index() < booted.index(),
|
||||
_ => false,
|
||||
};
|
||||
|
||||
// 7. Determine boot order
|
||||
let boot_order = if rollback_queued {
|
||||
BootOrder::Rollback
|
||||
} else {
|
||||
BootOrder::Default
|
||||
};
|
||||
|
||||
// 8. Create deployments structure
|
||||
let deployments = Deployments {
|
||||
staged,
|
||||
rollback,
|
||||
other: related_deployments,
|
||||
};
|
||||
|
||||
// 9. Create boot entries
|
||||
let staged = deployments.staged
|
||||
.as_ref()
|
||||
.map(|d| boot_entry_from_deployment(sysroot, d))
|
||||
.transpose()
|
||||
.context("Staged deployment")?;
|
||||
|
||||
let booted = booted_deployment
|
||||
.as_ref()
|
||||
.map(|d| boot_entry_from_deployment(sysroot, d))
|
||||
.transpose()
|
||||
.context("Booted deployment")?;
|
||||
|
||||
let rollback = deployments.rollback
|
||||
.as_ref()
|
||||
.map(|d| boot_entry_from_deployment(sysroot, d))
|
||||
.transpose()
|
||||
.context("Rollback deployment")?;
|
||||
|
||||
// 10. Create host specification
|
||||
let spec = staged
|
||||
.as_ref()
|
||||
.or(booted.as_ref())
|
||||
.and_then(|entry| entry.image.as_ref())
|
||||
.map(|img| HostSpec {
|
||||
image: Some(img.image.clone()),
|
||||
boot_order,
|
||||
})
|
||||
.unwrap_or_default();
|
||||
|
||||
// 11. Determine host type
|
||||
let ty = if booted
|
||||
.as_ref()
|
||||
.map(|b| b.image.is_some())
|
||||
.unwrap_or_default()
|
||||
{
|
||||
Some(HostType::BootcHost)
|
||||
} else {
|
||||
None
|
||||
};
|
||||
|
||||
// 12. Create host status
|
||||
let mut host = Host::new(spec);
|
||||
host.status = HostStatus {
|
||||
staged,
|
||||
booted,
|
||||
rollback,
|
||||
other_deployments: other_deployments,
|
||||
rollback_queued,
|
||||
ty,
|
||||
};
|
||||
|
||||
Ok((deployments, host))
|
||||
}
|
||||
```
|
||||
|
||||
## Data Structures
|
||||
|
||||
### 1. Host Structure
|
||||
|
||||
```rust
|
||||
pub struct Host {
|
||||
pub resource: k8sapitypes::Resource,
|
||||
pub spec: HostSpec,
|
||||
pub status: HostStatus,
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Host Specification
|
||||
|
||||
```rust
|
||||
pub struct HostSpec {
|
||||
pub image: Option<ImageReference>,
|
||||
pub boot_order: BootOrder,
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Host Status
|
||||
|
||||
```rust
|
||||
pub struct HostStatus {
|
||||
pub staged: Option<BootEntry>,
|
||||
pub booted: Option<BootEntry>,
|
||||
pub rollback: Option<BootEntry>,
|
||||
pub other_deployments: Vec<BootEntry>,
|
||||
pub rollback_queued: bool,
|
||||
pub ty: Option<HostType>,
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Boot Entry
|
||||
|
||||
```rust
|
||||
pub struct BootEntry {
|
||||
pub deployment: DeploymentInfo,
|
||||
pub image: Option<ImageStatus>,
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Image Status
|
||||
|
||||
```rust
|
||||
pub struct ImageStatus {
|
||||
pub image: ImageReference,
|
||||
pub version: Option<String>,
|
||||
pub timestamp: Option<chrono::DateTime<chrono::Utc>>,
|
||||
pub image_digest: String,
|
||||
pub architecture: String,
|
||||
}
|
||||
```
|
||||
|
||||
## Output Formats
|
||||
|
||||
### 1. Human Readable Format
|
||||
|
||||
**Default for terminal output**
|
||||
|
||||
```
|
||||
System is deployed via bootc.
|
||||
|
||||
Image: quay.io/myorg/debian-bootc:v2.0
|
||||
Version: 2.0.0
|
||||
Digest: sha256:abc123def456...
|
||||
Architecture: x86_64
|
||||
|
||||
Boot Order: Default
|
||||
Rollback Queued: false
|
||||
|
||||
Deployments:
|
||||
Staged: None
|
||||
Booted: quay.io/myorg/debian-bootc:v2.0
|
||||
Rollback: quay.io/myorg/debian-bootc:v1.0
|
||||
```
|
||||
|
||||
### 2. YAML Format
|
||||
|
||||
**Default for non-terminal output**
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Host
|
||||
metadata:
|
||||
name: localhost
|
||||
spec:
|
||||
image:
|
||||
image: quay.io/myorg/debian-bootc:v2.0
|
||||
transport: registry
|
||||
bootOrder: Default
|
||||
status:
|
||||
staged: null
|
||||
booted:
|
||||
deployment:
|
||||
id: abc123def456...
|
||||
osname: debian-bootc
|
||||
checksum: def456ghi789...
|
||||
image:
|
||||
image:
|
||||
image: quay.io/myorg/debian-bootc:v2.0
|
||||
transport: registry
|
||||
version: "2.0.0"
|
||||
timestamp: "2024-01-15T10:30:00Z"
|
||||
imageDigest: sha256:abc123def456...
|
||||
architecture: x86_64
|
||||
rollback:
|
||||
deployment:
|
||||
id: def456ghi789...
|
||||
osname: debian-bootc
|
||||
checksum: ghi789jkl012...
|
||||
image:
|
||||
image:
|
||||
image: quay.io/myorg/debian-bootc:v1.0
|
||||
transport: registry
|
||||
version: "1.0.0"
|
||||
timestamp: "2024-01-10T15:45:00Z"
|
||||
imageDigest: sha256:def456ghi789...
|
||||
architecture: x86_64
|
||||
otherDeployments: []
|
||||
rollbackQueued: false
|
||||
ty: BootcHost
|
||||
```
|
||||
|
||||
### 3. JSON Format
|
||||
|
||||
**For programmatic access**
|
||||
|
||||
```json
|
||||
{
|
||||
"apiVersion": "v1",
|
||||
"kind": "Host",
|
||||
"metadata": {
|
||||
"name": "localhost"
|
||||
},
|
||||
"spec": {
|
||||
"image": {
|
||||
"image": "quay.io/myorg/debian-bootc:v2.0",
|
||||
"transport": "registry"
|
||||
},
|
||||
"bootOrder": "Default"
|
||||
},
|
||||
"status": {
|
||||
"staged": null,
|
||||
"booted": {
|
||||
"deployment": {
|
||||
"id": "abc123def456...",
|
||||
"osname": "debian-bootc",
|
||||
"checksum": "def456ghi789..."
|
||||
},
|
||||
"image": {
|
||||
"image": {
|
||||
"image": "quay.io/myorg/debian-bootc:v2.0",
|
||||
"transport": "registry"
|
||||
},
|
||||
"version": "2.0.0",
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"imageDigest": "sha256:abc123def456...",
|
||||
"architecture": "x86_64"
|
||||
}
|
||||
},
|
||||
"rollback": {
|
||||
"deployment": {
|
||||
"id": "def456ghi789...",
|
||||
"osname": "debian-bootc",
|
||||
"checksum": "ghi789jkl012..."
|
||||
},
|
||||
"image": {
|
||||
"image": {
|
||||
"image": "quay.io/myorg/debian-bootc:v1.0",
|
||||
"transport": "registry"
|
||||
},
|
||||
"version": "1.0.0",
|
||||
"timestamp": "2024-01-10T15:45:00Z",
|
||||
"imageDigest": "sha256:def456ghi789...",
|
||||
"architecture": "x86_64"
|
||||
}
|
||||
},
|
||||
"otherDeployments": [],
|
||||
"rollbackQueued": false,
|
||||
"ty": "BootcHost"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Deployment Detection
|
||||
|
||||
### 1. OSTree Boot Detection
|
||||
|
||||
```rust
|
||||
if !ostree_booted()? {
|
||||
Default::default()
|
||||
} else {
|
||||
// Get system status
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Check if system is booted via OSTree
|
||||
**Process**: Verify OSTree boot environment
|
||||
|
||||
### 2. Deployment Partitioning
|
||||
|
||||
```rust
|
||||
let (mut related_deployments, other_deployments) = sysroot
|
||||
.deployments()
|
||||
.into_iter()
|
||||
.partition::<VecDeque<_>, _>(|d| Some(d.osname()) == stateroot);
|
||||
```
|
||||
|
||||
**Purpose**: Separate related deployments from others
|
||||
**Process**: Filter deployments by stateroot name
|
||||
|
||||
### 3. Staged Deployment Detection
|
||||
|
||||
```rust
|
||||
let staged = related_deployments
|
||||
.iter()
|
||||
.position(|d| d.is_staged())
|
||||
.map(|i| related_deployments.remove(i).unwrap());
|
||||
```
|
||||
|
||||
**Purpose**: Find staged deployment for next boot
|
||||
**Process**: Look for deployment marked as staged
|
||||
|
||||
### 4. Rollback Detection
|
||||
|
||||
```rust
|
||||
let rollback = related_deployments.pop_front();
|
||||
let rollback_queued = match (booted_deployment.as_ref(), rollback.as_ref()) {
|
||||
(Some(booted), Some(rollback)) => rollback.index() < booted.index(),
|
||||
_ => false,
|
||||
};
|
||||
```
|
||||
|
||||
**Purpose**: Determine rollback deployment and queued status
|
||||
**Process**: Check deployment order and indices
|
||||
|
||||
## Boot Order Management
|
||||
|
||||
### 1. Boot Order States
|
||||
|
||||
```rust
|
||||
let boot_order = if rollback_queued {
|
||||
BootOrder::Rollback
|
||||
} else {
|
||||
BootOrder::Default
|
||||
};
|
||||
```
|
||||
|
||||
**States**:
|
||||
- **Default**: Current deployment first, rollback second
|
||||
- **Rollback**: Rollback deployment first, current second
|
||||
|
||||
### 2. Rollback Queued Detection
|
||||
|
||||
```rust
|
||||
let rollback_queued = match (booted_deployment.as_ref(), rollback.as_ref()) {
|
||||
(Some(booted), Some(rollback)) => rollback.index() < booted.index(),
|
||||
_ => false,
|
||||
};
|
||||
```
|
||||
|
||||
**Purpose**: Determine if rollback is queued for next boot
|
||||
**Process**: Compare deployment indices
|
||||
|
||||
## Image Information Extraction
|
||||
|
||||
### 1. Image Status Creation
|
||||
|
||||
```rust
|
||||
fn create_imagestatus(
|
||||
image: ImageReference,
|
||||
manifest_digest: &Digest,
|
||||
config: &ImageConfiguration,
|
||||
) -> ImageStatus {
|
||||
let labels = labels_of_config(config);
|
||||
let timestamp = labels
|
||||
.and_then(|l| {
|
||||
l.get(oci_spec::image::ANNOTATION_CREATED)
|
||||
.map(|s| s.as_str())
|
||||
})
|
||||
.and_then(|s| chrono::DateTime::parse_from_rfc3339(s).ok())
|
||||
.map(|dt| dt.with_timezone(&chrono::Utc));
|
||||
|
||||
let architecture = config.architecture().unwrap_or("unknown").to_string();
|
||||
|
||||
ImageStatus {
|
||||
image,
|
||||
version: labels.and_then(|l| l.get("version").cloned()),
|
||||
timestamp,
|
||||
image_digest: manifest_digest.to_string(),
|
||||
architecture,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Extract image metadata and configuration
|
||||
**Process**: Parse OCI image configuration and labels
|
||||
|
||||
### 2. Boot Entry Creation
|
||||
|
||||
```rust
|
||||
fn boot_entry_from_deployment(
|
||||
sysroot: &SysrootLock,
|
||||
deployment: &ostree::Deployment,
|
||||
) -> Result<BootEntry> {
|
||||
let deployment_info = DeploymentInfo {
|
||||
id: deployment.csum().to_string(),
|
||||
osname: deployment.osname().to_string(),
|
||||
checksum: deployment.csum().to_string(),
|
||||
};
|
||||
|
||||
let image = if let Ok(origin) = deployment.origin() {
|
||||
if let Some(refspec) = origin.optional_string("origin", "refspec")? {
|
||||
if let Ok(ostree_ref) = ostree::parse_refspec(&refspec) {
|
||||
if let Ok(image_ref) = ostree_container::OstreeImageReference::try_from(ostree_ref) {
|
||||
let image_ref = ImageReference::from(image_ref);
|
||||
let repo = &sysroot.repo();
|
||||
let imgstate = ostree_container::store::query_image_commit(repo, &deployment.csum())?;
|
||||
let cached = imgstate.cached_update
|
||||
.map(|cached| create_imagestatus(image_ref, &cached.manifest_digest, &cached.config));
|
||||
cached
|
||||
} else {
|
||||
None
|
||||
}
|
||||
} else {
|
||||
None
|
||||
}
|
||||
} else {
|
||||
None
|
||||
}
|
||||
} else {
|
||||
None
|
||||
};
|
||||
|
||||
Ok(BootEntry {
|
||||
deployment: deployment_info,
|
||||
image,
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Create boot entry from OSTree deployment
|
||||
**Process**: Extract deployment info and image metadata
|
||||
|
||||
## Format Detection
|
||||
|
||||
### 1. Automatic Format Selection
|
||||
|
||||
```rust
|
||||
let legacy_opt = if opts.json {
|
||||
OutputFormat::Json
|
||||
} else if std::io::stdout().is_terminal() {
|
||||
OutputFormat::HumanReadable
|
||||
} else {
|
||||
OutputFormat::Yaml
|
||||
};
|
||||
```
|
||||
|
||||
**Logic**:
|
||||
- **JSON**: If `--json` flag specified
|
||||
- **Human Readable**: If output is a terminal
|
||||
- **YAML**: If output is not a terminal
|
||||
|
||||
### 2. Format Version Support
|
||||
|
||||
```rust
|
||||
match opts.format_version.unwrap_or_default() {
|
||||
0 | 1 => {} // Both 0 and 1 mean "v1"
|
||||
o => anyhow::bail!("Unsupported format version: {o}"),
|
||||
};
|
||||
```
|
||||
|
||||
**Purpose**: Support multiple format versions
|
||||
**Current**: Version 1 (exposed as both 0 and 1)
|
||||
|
||||
## Filtering Options
|
||||
|
||||
### 1. Booted Deployment Filter
|
||||
|
||||
```rust
|
||||
if opts.booted {
|
||||
host.filter_to_slot(Slot::Booted);
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Show only booted deployment information
|
||||
**Use Case**: Focus on current deployment
|
||||
|
||||
### 2. Verbose Output
|
||||
|
||||
```rust
|
||||
human_readable_output(&mut out, &host, opts.verbose)
|
||||
```
|
||||
|
||||
**Purpose**: Include additional fields in human readable format
|
||||
**Use Case**: Detailed troubleshooting information
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. OSTree Boot Detection Errors
|
||||
|
||||
```rust
|
||||
if !ostree_booted()? {
|
||||
Default::default()
|
||||
}
|
||||
```
|
||||
|
||||
**Error**: System not booted via OSTree
|
||||
**Response**: Return default empty status
|
||||
|
||||
### 2. Deployment Access Errors
|
||||
|
||||
```rust
|
||||
let (_deployments, host) = get_status(&ostree, booted_deployment.as_ref())?;
|
||||
```
|
||||
|
||||
**Error**: Cannot access deployments
|
||||
**Response**: Propagate error up the call stack
|
||||
|
||||
### 3. Format Version Errors
|
||||
|
||||
```rust
|
||||
match opts.format_version.unwrap_or_default() {
|
||||
0 | 1 => {}
|
||||
o => anyhow::bail!("Unsupported format version: {o}"),
|
||||
};
|
||||
```
|
||||
|
||||
**Error**: Unsupported format version
|
||||
**Response**: Return error with message
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### 1. Interactive Use
|
||||
|
||||
```bash
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check with verbose output
|
||||
bootc status --verbose
|
||||
|
||||
# Check only booted deployment
|
||||
bootc status --booted
|
||||
```
|
||||
|
||||
### 2. Programmatic Use
|
||||
|
||||
```bash
|
||||
# Get JSON output for parsing
|
||||
bootc status --format=json
|
||||
|
||||
# Get YAML output for parsing
|
||||
bootc status --format=yaml
|
||||
|
||||
# Check if system is bootc compatible
|
||||
bootc status --format=json | jq '.status.booted != null'
|
||||
```
|
||||
|
||||
### 3. Automation Scripts
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Check if rollback is queued
|
||||
if bootc status --format=json | jq -r '.status.rollbackQueued' | grep -q true; then
|
||||
echo "Rollback is queued for next boot"
|
||||
fi
|
||||
|
||||
# Get current image version
|
||||
CURRENT_VERSION=$(bootc status --format=json | jq -r '.status.booted.image.version // "unknown"')
|
||||
echo "Current version: $CURRENT_VERSION"
|
||||
```
|
||||
|
||||
## Integration with Other Commands
|
||||
|
||||
### 1. Relationship to bootc upgrade
|
||||
|
||||
**Status Before Upgrade**:
|
||||
```bash
|
||||
bootc status
|
||||
bootc upgrade --apply
|
||||
bootc status
|
||||
```
|
||||
|
||||
**Status After Upgrade**:
|
||||
- Shows new staged deployment
|
||||
- Shows updated booted deployment
|
||||
- Shows previous deployment as rollback
|
||||
|
||||
### 2. Relationship to bootc switch
|
||||
|
||||
**Status Before Switch**:
|
||||
```bash
|
||||
bootc status
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
bootc status
|
||||
```
|
||||
|
||||
**Status After Switch**:
|
||||
- Shows new image reference
|
||||
- Shows staged deployment
|
||||
- Shows updated boot order
|
||||
|
||||
### 3. Relationship to bootc rollback
|
||||
|
||||
**Status Before Rollback**:
|
||||
```bash
|
||||
bootc status
|
||||
bootc rollback
|
||||
bootc status
|
||||
```
|
||||
|
||||
**Status After Rollback**:
|
||||
- Shows rollback queued status
|
||||
- Shows updated boot order
|
||||
- Shows deployment reordering
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### System Not Bootc Compatible
|
||||
```bash
|
||||
# Check if system is bootc compatible
|
||||
bootc status --format=json | jq '.status.booted != null'
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
#### No Deployments Found
|
||||
```bash
|
||||
# Check deployment status
|
||||
ostree admin status
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### Format Parsing Errors
|
||||
```bash
|
||||
# Use specific format
|
||||
bootc status --format=json
|
||||
|
||||
# Check format version
|
||||
bootc status --format-version=1
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc status
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status --verbose
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Programmatic Usage
|
||||
|
||||
- **Use JSON/YAML**: For programmatic parsing
|
||||
- **Check Format Version**: Specify format version explicitly
|
||||
- **Handle Errors**: Check for null values and errors
|
||||
- **Validate Output**: Verify expected fields exist
|
||||
|
||||
### 2. Interactive Usage
|
||||
|
||||
- **Use Human Readable**: For interactive use
|
||||
- **Use Verbose**: For detailed information
|
||||
- **Check Booted**: Focus on current deployment
|
||||
- **Monitor Changes**: Track status over time
|
||||
|
||||
### 3. Automation
|
||||
|
||||
- **Parse JSON**: Use `jq` for JSON parsing
|
||||
- **Check Compatibility**: Verify bootc compatibility
|
||||
- **Monitor Status**: Track deployment changes
|
||||
- **Handle Errors**: Implement proper error handling
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Additional Formats**: Support for more output formats
|
||||
- **Filtering Options**: More granular filtering
|
||||
- **Status History**: Track status changes over time
|
||||
- **Health Checks**: Include system health information
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for status queries
|
||||
- **Web Interface**: Web-based status display
|
||||
- **Monitoring Integration**: Integration with monitoring systems
|
||||
- **Alerting**: Status-based alerting
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc status system's architecture, implementation, and usage patterns.
|
||||
897
switch/bootc-switch-external-commands.md
Normal file
897
switch/bootc-switch-external-commands.md
Normal file
|
|
@ -0,0 +1,897 @@
|
|||
# bootc switch - 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 switch` system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc switch into larger systems.
|
||||
|
||||
## Core System Commands
|
||||
|
||||
### 1. bootc Commands
|
||||
|
||||
#### bootc switch
|
||||
**Purpose**: Switch to different container image reference
|
||||
**Usage**: `bootc switch [OPTIONS...] <TARGET>`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment management
|
||||
- `podman` - For container registry access
|
||||
- `systemd` - For service management and reboot
|
||||
|
||||
```bash
|
||||
# Switch to different image version
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch and apply immediately
|
||||
bootc switch --apply quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch with soft reboot
|
||||
bootc switch --apply --soft-reboot=auto quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch with specific transport
|
||||
bootc switch --transport=oci-archive quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### 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 upgrade
|
||||
**Purpose**: Update current image to newer version
|
||||
**Usage**: `bootc upgrade [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment management
|
||||
- `podman` - For container registry access
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# Download and stage updates
|
||||
bootc upgrade
|
||||
|
||||
# Apply updates and reboot
|
||||
bootc upgrade --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
|
||||
```
|
||||
|
||||
#### ostree refs
|
||||
**Purpose**: List OSTree references
|
||||
**Usage**: `ostree refs [OPTIONS...]`
|
||||
**Integration**: Used for reference management
|
||||
|
||||
```bash
|
||||
# List all references
|
||||
ostree refs
|
||||
|
||||
# List references for specific remote
|
||||
ostree refs --remote=quay.io
|
||||
|
||||
# List references with details
|
||||
ostree refs --list
|
||||
```
|
||||
|
||||
### 3. Container Registry Commands
|
||||
|
||||
#### podman pull
|
||||
**Purpose**: Pull container images from registry
|
||||
**Usage**: `podman pull [OPTIONS...] IMAGE`
|
||||
**Integration**: Used by bootc for downloading images
|
||||
|
||||
```bash
|
||||
# Pull image from registry
|
||||
podman pull quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Pull with authentication
|
||||
podman pull --creds=username:password quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Pull specific tag
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
#### 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:v2.0
|
||||
|
||||
# Inspect specific configuration
|
||||
podman inspect --format='{{.Config.Labels}}' quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Inspect manifest
|
||||
podman inspect --format='{{.Manifest}}' quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### podman images
|
||||
**Purpose**: List container images
|
||||
**Usage**: `podman images [OPTIONS...]`
|
||||
**Integration**: Used for image management
|
||||
|
||||
```bash
|
||||
# List all images
|
||||
podman images
|
||||
|
||||
# List images with specific format
|
||||
podman images --format "table {{.Repository}} {{.Tag}} {{.ID}}"
|
||||
|
||||
# List images with filters
|
||||
podman images --filter "reference=quay.io/myorg/*"
|
||||
```
|
||||
|
||||
#### podman rmi
|
||||
**Purpose**: Remove container images
|
||||
**Usage**: `podman rmi [OPTIONS...] IMAGE`
|
||||
**Integration**: Used for image cleanup
|
||||
|
||||
```bash
|
||||
# Remove specific image
|
||||
podman rmi quay.io/myorg/debian-bootc:v1.0
|
||||
|
||||
# Remove image by ID
|
||||
podman rmi abc123def456
|
||||
|
||||
# Remove unused images
|
||||
podman image prune
|
||||
```
|
||||
|
||||
### 4. System Management Commands
|
||||
|
||||
#### systemctl
|
||||
**Purpose**: Control systemd services and units
|
||||
**Usage**: `systemctl [COMMAND] [UNIT...]`
|
||||
**Integration**: Used for service management and reboot coordination
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-fetch-apply-updates.service
|
||||
|
||||
# Start service
|
||||
systemctl start bootc-fetch-apply-updates.service
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-fetch-apply-updates.service
|
||||
|
||||
# Restart service
|
||||
systemctl restart bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### reboot
|
||||
**Purpose**: Reboot the system
|
||||
**Usage**: `reboot [OPTIONS...]`
|
||||
**Integration**: Used by `bootc switch --apply` for system restart
|
||||
|
||||
```bash
|
||||
# Reboot system
|
||||
reboot
|
||||
|
||||
# Reboot with specific delay
|
||||
reboot +5
|
||||
|
||||
# Reboot with message
|
||||
reboot "Applying bootc switch"
|
||||
```
|
||||
|
||||
#### shutdown
|
||||
**Purpose**: Shutdown the system
|
||||
**Usage**: `shutdown [OPTIONS...]`
|
||||
**Integration**: Used for controlled shutdown before reboot
|
||||
|
||||
```bash
|
||||
# Shutdown system
|
||||
shutdown -h now
|
||||
|
||||
# Shutdown with delay
|
||||
shutdown -h +5
|
||||
|
||||
# Shutdown with message
|
||||
shutdown -h now "Applying bootc switch"
|
||||
```
|
||||
|
||||
## Network and Registry Commands
|
||||
|
||||
### 1. HTTP Clients
|
||||
|
||||
#### curl
|
||||
**Purpose**: HTTP client for registry communication
|
||||
**Usage**: `curl [OPTIONS...] URL`
|
||||
**Integration**: Used for registry API calls and authentication
|
||||
|
||||
```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/v2.0
|
||||
|
||||
# Authenticate with registry
|
||||
curl -u username:password https://quay.io/v2/token
|
||||
```
|
||||
|
||||
#### 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/v2.0
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
### 3. Network Troubleshooting
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
#### traceroute
|
||||
**Purpose**: Trace network path
|
||||
**Usage**: `traceroute [OPTIONS...] HOST`
|
||||
**Integration**: Used for network path analysis
|
||||
|
||||
```bash
|
||||
# Trace path to registry
|
||||
traceroute quay.io
|
||||
|
||||
# Trace with specific options
|
||||
traceroute -n quay.io
|
||||
```
|
||||
|
||||
## 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 /etc/bootc/config.yaml
|
||||
|
||||
# Display with line numbers
|
||||
cat -n /etc/bootc/config.yaml
|
||||
|
||||
# Display non-printing characters
|
||||
cat -v /etc/bootc/config.yaml
|
||||
```
|
||||
|
||||
#### cp
|
||||
**Purpose**: Copy files
|
||||
**Usage**: `cp [OPTIONS...] SOURCE DEST`
|
||||
**Integration**: Used for backing up configuration files
|
||||
|
||||
```bash
|
||||
# Copy file
|
||||
cp /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
|
||||
|
||||
# Copy with preserve attributes
|
||||
cp -p /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
|
||||
|
||||
# Copy recursively
|
||||
cp -r /etc/bootc/ /etc/bootc.backup/
|
||||
```
|
||||
|
||||
#### mv
|
||||
**Purpose**: Move or rename files
|
||||
**Usage**: `mv [OPTIONS...] SOURCE DEST`
|
||||
**Integration**: Used for renaming configuration files
|
||||
|
||||
```bash
|
||||
# Rename file
|
||||
mv /etc/bootc/config.yaml /etc/bootc/config.yaml.old
|
||||
|
||||
# Move file
|
||||
mv /etc/bootc/config.yaml /backup/config.yaml
|
||||
```
|
||||
|
||||
#### rm
|
||||
**Purpose**: Remove files
|
||||
**Usage**: `rm [OPTIONS...] FILE...`
|
||||
**Integration**: Used for cleaning up temporary files
|
||||
|
||||
```bash
|
||||
# Remove file
|
||||
rm /etc/bootc/config.yaml
|
||||
|
||||
# Remove with confirmation
|
||||
rm -i /etc/bootc/config.yaml
|
||||
|
||||
# Remove recursively
|
||||
rm -r /etc/bootc/
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## 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 /etc/bootc/config.yaml
|
||||
|
||||
# Display first bytes
|
||||
head -c 100 /etc/bootc/config.yaml
|
||||
```
|
||||
|
||||
## Security Commands
|
||||
|
||||
### 1. Signature Verification
|
||||
|
||||
#### 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
|
||||
|
||||
# Generate key pair
|
||||
openssl genrsa -out private.key 2048
|
||||
```
|
||||
|
||||
### 2. File Permissions
|
||||
|
||||
#### chmod
|
||||
**Purpose**: Change file permissions
|
||||
**Usage**: `chmod [OPTIONS...] MODE FILE...`
|
||||
**Integration**: Used for setting file permissions
|
||||
|
||||
```bash
|
||||
# Set permissions
|
||||
chmod 644 /etc/bootc/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 /etc/bootc/config.yaml
|
||||
|
||||
# Change ownership recursively
|
||||
chown -R root:root /etc/bootc
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Container Runtime Commands
|
||||
|
||||
### 1. Podman Commands
|
||||
|
||||
#### podman run
|
||||
**Purpose**: Run container
|
||||
**Usage**: `podman run [OPTIONS...] IMAGE [COMMAND...]`
|
||||
**Integration**: Used for testing container images
|
||||
|
||||
```bash
|
||||
# Run container
|
||||
podman run -it quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Run with specific options
|
||||
podman run --rm quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Run with environment variables
|
||||
podman run -e VAR=value quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### podman ps
|
||||
**Purpose**: List containers
|
||||
**Usage**: `podman ps [OPTIONS...]`
|
||||
**Integration**: Used for container management
|
||||
|
||||
```bash
|
||||
# List running containers
|
||||
podman ps
|
||||
|
||||
# List all containers
|
||||
podman ps -a
|
||||
|
||||
# List with specific format
|
||||
podman ps --format "table {{.Names}} {{.Image}} {{.Status}}"
|
||||
```
|
||||
|
||||
#### podman rm
|
||||
**Purpose**: Remove containers
|
||||
**Usage**: `podman rm [OPTIONS...] CONTAINER...`
|
||||
**Integration**: Used for container cleanup
|
||||
|
||||
```bash
|
||||
# Remove specific container
|
||||
podman rm container-id
|
||||
|
||||
# Remove all stopped containers
|
||||
podman container prune
|
||||
|
||||
# Remove with force
|
||||
podman rm -f container-id
|
||||
```
|
||||
|
||||
### 2. Docker Commands (Alternative)
|
||||
|
||||
#### docker
|
||||
**Purpose**: Alternative container runtime
|
||||
**Usage**: `docker [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Alternative to podman
|
||||
|
||||
```bash
|
||||
# List containers
|
||||
docker ps -a
|
||||
|
||||
# List images
|
||||
docker images
|
||||
|
||||
# Run container
|
||||
docker run -it quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
## 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 /etc/bootc/config.yaml
|
||||
|
||||
# Commit changes
|
||||
git commit -m "Update configuration"
|
||||
|
||||
# Check status
|
||||
git status
|
||||
```
|
||||
|
||||
## System Information Commands
|
||||
|
||||
### 1. 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
|
||||
```
|
||||
|
||||
### 2. Hardware Information
|
||||
|
||||
#### lscpu
|
||||
**Purpose**: Display CPU information
|
||||
**Usage**: `lscpu [OPTIONS...]`
|
||||
**Integration**: Used for system resource analysis
|
||||
|
||||
```bash
|
||||
# Display CPU information
|
||||
lscpu
|
||||
|
||||
# Display in specific format
|
||||
lscpu --extended
|
||||
```
|
||||
|
||||
#### lsblk
|
||||
**Purpose**: List block devices
|
||||
**Usage**: `lsblk [OPTIONS...]`
|
||||
**Integration**: Used for storage device identification
|
||||
|
||||
```bash
|
||||
# List all block devices
|
||||
lsblk
|
||||
|
||||
# List with filesystem information
|
||||
lsblk -f
|
||||
|
||||
# List specific device
|
||||
lsblk /dev/sda
|
||||
```
|
||||
|
||||
This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc switch system.
|
||||
381
switch/bootc-switch-flowchart.md
Normal file
381
switch/bootc-switch-flowchart.md
Normal file
|
|
@ -0,0 +1,381 @@
|
|||
# bootc switch - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc switch` process flow, showing the decision points, operations, and state transitions involved in switching container image references.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc switch │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Target Image │
|
||||
│ │
|
||||
│ • Parse transport type (registry, oci, oci-archive, etc.) │
|
||||
│ • Create ImageReference structure │
|
||||
│ • Configure signature verification policy │
|
||||
│ • Convert to OSTreeImageReference │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Operation Mode │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ In-Place Mutation? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ In-Place ││ │ │ Normal Switch Process ││ │
|
||||
│ │ │ Switch ││ │ │ ││ │
|
||||
│ │ │ • Find ││ │ │ • Get system storage ││ │
|
||||
│ │ │ deployment││ │ │ • Get OSTree repository ││ │
|
||||
│ │ │ • Update ││ │ │ • Get current system status ││ │
|
||||
│ │ │ origin ││ │ │ • Create new specification ││ │
|
||||
│ │ │ • Log ││ │ │ • Check for changes ││ │
|
||||
│ │ │ operation ││ │ │ • Pull and stage image ││ │
|
||||
│ │ └─────────────┘│ │ │ • Update system status ││ │
|
||||
│ │ │ │ │ • Handle soft reboot ││ │
|
||||
│ │ ┌─────────────┐│ │ │ • Apply changes if requested ││ │
|
||||
│ │ │ Return ││ │ └─────────────────────────────────┘│ │
|
||||
│ │ │ Success ││ │ │ │
|
||||
│ │ └─────────────┘│ │ │ │
|
||||
│ └─────────────────┘ │ │ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Get System Status │
|
||||
│ │
|
||||
│ • Get storage interface │
|
||||
│ • Get OSTree repository │
|
||||
│ • Get current system status │
|
||||
│ • Get booted deployment information │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create New Specification │
|
||||
│ │
|
||||
│ • Clone current host specification │
|
||||
│ • Update image reference to target │
|
||||
│ • Preserve other settings (boot order, etc.) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check for Changes │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ new_spec == host.spec? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Print: ││ │ │ Log Switch Operation ││ │
|
||||
│ │ │ "Image ││ │ │ • Log old image reference ││ │
|
||||
│ │ │ specification││ │ │ • Log new image reference ││ │
|
||||
│ │ │ is ││ │ │ • Log transport type ││ │
|
||||
│ │ │ unchanged" ││ │ │ • Log to systemd journal ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ▼ │ │
|
||||
│ │ │ Return ││ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Success ││ │ │ Pull and Stage Image ││ │
|
||||
│ │ └─────────────┘│ │ │ • Authenticate with registry ││ │
|
||||
│ └─────────────────┘ │ │ • Download image layers ││ │
|
||||
│ │ │ • Convert to OSTree format ││ │
|
||||
│ │ │ • Validate image compatibility ││ │
|
||||
│ │ │ • Stage new deployment ││ │
|
||||
│ │ └─────────────────────────────────┘│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Handle Image Retention │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --retain specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Keep ││ │ │ Prune Previous Reference ││ │
|
||||
│ │ │ Previous ││ │ │ • Get booted deployment origin ││ │
|
||||
│ │ │ Image ││ │ │ • Parse OSTree reference ││ │
|
||||
│ │ │ Reference ││ │ │ • Update OSTree reference ││ │
|
||||
│ │ └─────────────┘│ │ │ • Free up disk space ││ │
|
||||
│ └─────────────────┘ │ └─────────────────────────────────┘│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Stage New Deployment │
|
||||
│ │
|
||||
│ • Create new deployment in OSTree │
|
||||
│ • Configure bootloader for new deployment │
|
||||
│ • Update system status │
|
||||
│ • Preserve /etc and /var state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Update System Status │
|
||||
│ │
|
||||
│ • Update system modification time │
|
||||
│ • Refresh system status │
|
||||
│ • Update deployment information │
|
||||
│ • Log configuration changes │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Handle Soft Reboot │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --soft-reboot specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Configure ││ │ │ Skip Soft Reboot ││ │
|
||||
│ │ │ Soft Reboot ││ │ │ ││ │
|
||||
│ │ │ • Check ││ │ │ • Continue to apply check ││ │
|
||||
│ │ │ availability││ │ │ ││ │
|
||||
│ │ │ • Configure ││ │ │ ││ │
|
||||
│ │ │ if needed ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Apply Changes │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --apply specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Reboot ││ │ │ Changes Staged ││ │
|
||||
│ │ │ System ││ │ │ ││ │
|
||||
│ │ │ • Execute ││ │ │ • Changes ready for next boot ││ │
|
||||
│ │ │ reboot ││ │ │ • No immediate action ││ │
|
||||
│ │ │ • Apply ││ │ │ • User can reboot manually ││ │
|
||||
│ │ │ changes ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Image switch completed successfully │
|
||||
│ • New image staged for next boot │
|
||||
│ • System ready for reboot (if --apply) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## In-Place Switch Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ In-Place Switch │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Log Operation │
|
||||
│ │
|
||||
│ • Log to systemd journal with unique message ID │
|
||||
│ • Include image reference and transport type │
|
||||
│ • Mark as in-place switch operation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Find Deployment Directory │
|
||||
│ │
|
||||
│ • Search for deployment directory in /sysroot/ostree/deploy │
|
||||
│ • Locate current booted deployment │
|
||||
│ • Validate deployment structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Update Origin File │
|
||||
│ │
|
||||
│ • Read current origin file │
|
||||
│ • Parse origin configuration │
|
||||
│ • Update image reference │
|
||||
│ • Write updated origin file │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Extract Deployment ID │
|
||||
│ │
|
||||
│ • Parse deployment directory name │
|
||||
│ • Extract deployment ID │
|
||||
│ • Return deployment ID for logging │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • In-place switch completed │
|
||||
│ │ • Deployment ID updated │
|
||||
│ │ • Image reference changed │
|
||||
│ │ • System ready for next boot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Image │ │ System │ │ Network │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Invalid │ │ • Not bootc │ │ • Registry │ │
|
||||
│ │ transport │ │ compatible │ │ connectivity │ │
|
||||
│ │ • Image not │ │ • No deployment │ │ • Authentication│ │
|
||||
│ │ found │ │ found │ │ failed │ │
|
||||
│ │ • Signature │ │ • Invalid │ │ • Image pull │ │
|
||||
│ │ verification │ │ state │ │ failed │ │
|
||||
│ │ failed │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up any partial state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Current State │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Image: v1.0 │ │ Image: v1.0 │ │
|
||||
│ │ Boot: normal │ │ Boot: normal │ │
|
||||
│ │ Staged: none │ │ Staged: v2.0 │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Switch 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 │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Transport Type Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Transport Selection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Transport Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --transport specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use ││ │ │ Use Default (registry) ││ │
|
||||
│ │ │ Specified ││ │ │ ││ │
|
||||
│ │ │ Transport ││ │ │ • Set transport to 'registry' ││ │
|
||||
│ │ │ • registry ││ │ │ • Use registry authentication ││ │
|
||||
│ │ │ • oci ││ │ │ • Use HTTPS protocol ││ │
|
||||
│ │ │ • oci- ││ │ │ ││ │
|
||||
│ │ │ archive ││ │ │ ││ │
|
||||
│ │ │ • containers││ │ │ ││ │
|
||||
│ │ │ -storage ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Image Reference │
|
||||
│ │
|
||||
│ • Create ImageReference structure │
|
||||
│ • Set transport type │
|
||||
│ │ • Set image name/tag │
|
||||
│ │ • Configure signature verification │
|
||||
│ │ • Convert to OSTreeImageReference │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc switch process, showing all decision points, operations, and state transitions involved in switching container image references.
|
||||
607
switch/bootc-switch-technical-guide.md
Normal file
607
switch/bootc-switch-technical-guide.md
Normal file
|
|
@ -0,0 +1,607 @@
|
|||
# bootc switch - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc switch` is a command for changing the container image reference that a bootc-managed system will boot from. It operates similarly to `bootc upgrade` but changes the image source rather than updating the current image. This enables blue/green deployments, A/B testing, and controlled rollouts across different image versions.
|
||||
|
||||
## Purpose
|
||||
|
||||
The switch command serves several critical functions:
|
||||
|
||||
1. **Image Source Management**: Change the container image reference for future boots
|
||||
2. **Blue/Green Deployments**: Switch between different image versions
|
||||
3. **A/B Testing**: Test different image versions on different systems
|
||||
4. **Controlled Rollouts**: Gradually migrate systems to new image versions
|
||||
5. **Rollback Capability**: Switch back to previous image versions
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc switch [OPTIONS...] <TARGET>
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Switch to different image version
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch and apply immediately
|
||||
bootc switch --apply quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch with soft reboot
|
||||
bootc switch --apply --soft-reboot=auto quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch with specific transport
|
||||
bootc switch --transport=oci-archive quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
### Core Options
|
||||
|
||||
| Option | Description | Default | Required |
|
||||
|--------|-------------|---------|----------|
|
||||
| `TARGET` | Target image to use for next boot | `None` | Yes |
|
||||
| `--apply` | Restart/reboot into new target image | `false` | No |
|
||||
| `--quiet` | Don't display progress | `false` | No |
|
||||
| `--soft-reboot` | Configure soft reboot behavior | `None` | No |
|
||||
|
||||
### Transport Options
|
||||
|
||||
| Option | Description | Default | Values |
|
||||
|--------|-------------|---------|--------|
|
||||
| `--transport` | Container transport type | `registry` | `registry`, `oci`, `oci-archive`, `containers-storage` |
|
||||
|
||||
### Security Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--enforce-container-sigpolicy` | Enforce container signature policy | `false` |
|
||||
|
||||
### Advanced Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--retain` | Retain reference to currently booted image | `false` |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 1. Switch Command Structure
|
||||
|
||||
```rust
|
||||
pub(crate) struct SwitchOpts {
|
||||
pub(crate) quiet: bool, // Suppress progress output
|
||||
pub(crate) apply: bool, // Apply and reboot
|
||||
pub(crate) soft_reboot: Option<SoftRebootMode>, // Soft reboot behavior
|
||||
pub(crate) transport: String, // Container transport
|
||||
pub(crate) enforce_container_sigpolicy: bool, // Signature enforcement
|
||||
pub(crate) retain: bool, // Retain current image ref
|
||||
pub(crate) mutate_in_place: bool, // In-place mutation (hidden)
|
||||
pub(crate) progress: ProgressOptions, // Progress reporting
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Switch Process Flow
|
||||
|
||||
```rust
|
||||
async fn switch(opts: SwitchOpts) -> Result<()> {
|
||||
// 1. Parse and validate target image
|
||||
let transport = ostree_container::Transport::try_from(opts.transport.as_str())?;
|
||||
let imgref = ostree_container::ImageReference {
|
||||
transport,
|
||||
name: opts.target.to_string(),
|
||||
};
|
||||
let sigverify = sigpolicy_from_opt(opts.enforce_container_sigpolicy);
|
||||
let target = ostree_container::OstreeImageReference { sigverify, imgref };
|
||||
let target = ImageReference::from(target);
|
||||
|
||||
// 2. Handle in-place mutation (hidden option)
|
||||
if opts.mutate_in_place {
|
||||
let deployid = switch_origin_inplace(&root, &target).await?;
|
||||
println!("Updated {deployid} to pull from {target}");
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
// 3. Get system status
|
||||
let sysroot = &get_storage().await?;
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = &ostree.repo();
|
||||
let (booted_deployment, _deployments, host) =
|
||||
crate::status::get_status_require_booted(ostree)?;
|
||||
|
||||
// 4. Create new specification
|
||||
let new_spec = {
|
||||
let mut new_spec = host.spec.clone();
|
||||
new_spec.image = Some(target.clone());
|
||||
new_spec
|
||||
};
|
||||
|
||||
// 5. Check for changes
|
||||
if new_spec == host.spec {
|
||||
println!("Image specification is unchanged.");
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
// 6. Log switch operation
|
||||
tracing::info!(
|
||||
message_id = SWITCH_JOURNAL_ID,
|
||||
bootc.old_image_reference = old_image,
|
||||
bootc.new_image_reference = &target.image,
|
||||
"Switching from image {} to {}",
|
||||
old_image, target.image
|
||||
);
|
||||
|
||||
// 7. Pull and stage new image
|
||||
let fetched = crate::deploy::pull(repo, &target, None, opts.quiet, prog.clone()).await?;
|
||||
|
||||
// 8. Handle image retention
|
||||
if !opts.retain {
|
||||
// Prune previous ostree ref
|
||||
if let Some(booted_origin) = booted_deployment.origin() {
|
||||
if let Some(ostree_ref) = booted_origin.optional_string("origin", "refspec")? {
|
||||
let (remote, ostree_ref) = ostree::parse_refspec(&ostree_ref)?;
|
||||
repo.set_ref_immediate(remote.as_deref(), &ostree_ref, None, cancellable)?;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 9. Stage new deployment
|
||||
let stateroot = booted_deployment.osname();
|
||||
crate::deploy::stage(sysroot, &stateroot, &fetched, &new_spec, prog.clone()).await?;
|
||||
|
||||
// 10. Update system status
|
||||
sysroot.update_mtime()?;
|
||||
|
||||
// 11. Handle soft reboot
|
||||
if opts.soft_reboot.is_some() {
|
||||
let updated_host = crate::status::get_status(ostree, Some(&booted_deployment))?.1;
|
||||
handle_staged_soft_reboot(ostree, opts.soft_reboot, &updated_host)?;
|
||||
}
|
||||
|
||||
// 12. Apply changes if requested
|
||||
if opts.apply {
|
||||
crate::reboot::reboot()?;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Image Reference Handling
|
||||
|
||||
### 1. Transport Types
|
||||
|
||||
The switch command supports multiple container transport types:
|
||||
|
||||
#### Registry Transport (default)
|
||||
```bash
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### OCI Archive Transport
|
||||
```bash
|
||||
bootc switch --transport=oci-archive /path/to/image.tar
|
||||
```
|
||||
|
||||
#### OCI Transport
|
||||
```bash
|
||||
bootc switch --transport=oci oci:quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### Containers Storage Transport
|
||||
```bash
|
||||
bootc switch --transport=containers-storage containers-storage:quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
### 2. Image Reference Parsing
|
||||
|
||||
```rust
|
||||
let transport = ostree_container::Transport::try_from(opts.transport.as_str())?;
|
||||
let imgref = ostree_container::ImageReference {
|
||||
transport,
|
||||
name: opts.target.to_string(),
|
||||
};
|
||||
let sigverify = sigpolicy_from_opt(opts.enforce_container_sigpolicy);
|
||||
let target = ostree_container::OstreeImageReference { sigverify, imgref };
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. **Transport Parsing**: Convert string to transport enum
|
||||
2. **Image Reference**: Create container image reference
|
||||
3. **Signature Verification**: Configure signature policy
|
||||
4. **OSTree Reference**: Convert to OSTree image reference
|
||||
|
||||
## In-Place Mutation
|
||||
|
||||
### 1. In-Place Switch Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) fn switch_origin_inplace(root: &Dir, imgref: &ImageReference) -> Result<String> {
|
||||
const SWITCH_INPLACE_JOURNAL_ID: &str = "3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7";
|
||||
|
||||
tracing::info!(
|
||||
message_id = SWITCH_INPLACE_JOURNAL_ID,
|
||||
bootc.image.reference = &imgref.image,
|
||||
bootc.image.transport = &imgref.transport,
|
||||
bootc.switch_type = "in_place",
|
||||
"Performing in-place switch to image: {}",
|
||||
imgref
|
||||
);
|
||||
|
||||
// Find deployment directory
|
||||
let deploy_dir = find_deployment_directory(root)?;
|
||||
|
||||
// Update origin file
|
||||
let origin_path = deploy_dir.join("origin");
|
||||
let mut origin = std::fs::read_to_string(&origin_path)?;
|
||||
|
||||
// Update image reference in origin
|
||||
update_origin_image_reference(&mut origin, imgref)?;
|
||||
|
||||
// Write updated origin
|
||||
std::fs::write(&origin_path, origin)?;
|
||||
|
||||
// Extract deployment ID
|
||||
let deploy_id = extract_deployment_id(&deploy_dir)?;
|
||||
|
||||
Ok(deploy_id)
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Directly modify the booted deployment's origin file
|
||||
**Use Cases**:
|
||||
- Anaconda %post scripts
|
||||
- System installation scenarios
|
||||
- Emergency image switching
|
||||
|
||||
## State Management
|
||||
|
||||
### 1. Specification Updates
|
||||
|
||||
```rust
|
||||
let new_spec = {
|
||||
let mut new_spec = host.spec.clone();
|
||||
new_spec.image = Some(target.clone());
|
||||
new_spec
|
||||
};
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. **Clone Current Spec**: Copy existing host specification
|
||||
2. **Update Image Reference**: Set new target image
|
||||
3. **Preserve Other Settings**: Keep boot order and other settings
|
||||
|
||||
### 2. Change Detection
|
||||
|
||||
```rust
|
||||
if new_spec == host.spec {
|
||||
println!("Image specification is unchanged.");
|
||||
return Ok(());
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Avoid unnecessary operations when no changes are made
|
||||
**Benefits**: Performance optimization, clear user feedback
|
||||
|
||||
### 3. Image Retention
|
||||
|
||||
```rust
|
||||
if !opts.retain {
|
||||
// Prune previous ostree ref
|
||||
if let Some(booted_origin) = booted_deployment.origin() {
|
||||
if let Some(ostree_ref) = booted_origin.optional_string("origin", "refspec")? {
|
||||
let (remote, ostree_ref) = ostree::parse_refspec(&ostree_ref)?;
|
||||
repo.set_ref_immediate(remote.as_deref(), &ostree_ref, None, cancellable)?;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Manage OSTree references for disk space optimization
|
||||
**Behavior**:
|
||||
- **Default**: Remove previous image reference
|
||||
- **With `--retain`**: Keep previous image reference
|
||||
|
||||
## Logging and Monitoring
|
||||
|
||||
### 1. Switch Operation Logging
|
||||
|
||||
```rust
|
||||
const SWITCH_JOURNAL_ID: &str = "7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1";
|
||||
|
||||
tracing::info!(
|
||||
message_id = SWITCH_JOURNAL_ID,
|
||||
bootc.old_image_reference = old_image,
|
||||
bootc.new_image_reference = &target.image,
|
||||
bootc.new_image_transport = &target.transport,
|
||||
"Switching from image {} to {}",
|
||||
old_image, target.image
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Track image switching operations
|
||||
**Fields**:
|
||||
- `message_id`: Unique identifier for switch operations
|
||||
- `bootc.old_image_reference`: Previous image reference
|
||||
- `bootc.new_image_reference`: New image reference
|
||||
- `bootc.new_image_transport`: Transport type used
|
||||
|
||||
### 2. In-Place Switch Logging
|
||||
|
||||
```rust
|
||||
const SWITCH_INPLACE_JOURNAL_ID: &str = "3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7";
|
||||
|
||||
tracing::info!(
|
||||
message_id = SWITCH_INPLACE_JOURNAL_ID,
|
||||
bootc.image.reference = &imgref.image,
|
||||
bootc.image.transport = &imgref.transport,
|
||||
bootc.switch_type = "in_place",
|
||||
"Performing in-place switch to image: {}",
|
||||
imgref
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Track in-place switch operations
|
||||
**Fields**:
|
||||
- `message_id`: Unique identifier for in-place switches
|
||||
- `bootc.image.reference`: Target image reference
|
||||
- `bootc.image.transport`: Transport type used
|
||||
- `bootc.switch_type`: Operation type identifier
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### 1. Blue/Green Deployments
|
||||
|
||||
```bash
|
||||
# Deploy to green environment
|
||||
bootc switch quay.io/myorg/debian-bootc:green
|
||||
|
||||
# Switch back to blue if needed
|
||||
bootc switch quay.io/myorg/debian-bootc:blue
|
||||
```
|
||||
|
||||
### 2. A/B Testing
|
||||
|
||||
```bash
|
||||
# Switch subset of systems to version B
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0-beta
|
||||
|
||||
# Monitor and switch back if issues
|
||||
bootc switch quay.io/myorg/debian-bootc:v1.0-stable
|
||||
```
|
||||
|
||||
### 3. Controlled Rollouts
|
||||
|
||||
```bash
|
||||
# Switch to new version
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Apply immediately
|
||||
bootc switch --apply quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Apply with soft reboot
|
||||
bootc switch --apply --soft-reboot=auto quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
### 4. Emergency Rollbacks
|
||||
|
||||
```bash
|
||||
# Quick rollback to previous version
|
||||
bootc switch quay.io/myorg/debian-bootc:v1.0 --apply
|
||||
|
||||
# Rollback with retention
|
||||
bootc switch --retain quay.io/myorg/debian-bootc:v1.0
|
||||
```
|
||||
|
||||
## Integration with Other Commands
|
||||
|
||||
### 1. Relationship to bootc upgrade
|
||||
|
||||
**Similarities**:
|
||||
- Both pull and stage container images
|
||||
- Both support `--apply` and `--soft-reboot` options
|
||||
- Both use the same deployment staging process
|
||||
|
||||
**Differences**:
|
||||
- `upgrade`: Updates current image to newer version
|
||||
- `switch`: Changes image source to different image
|
||||
|
||||
### 2. Relationship to bootc rollback
|
||||
|
||||
**Complementary**:
|
||||
- `switch`: Change to different image version
|
||||
- `rollback`: Revert to previous deployment
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Switch to new version
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# If issues, rollback
|
||||
bootc rollback
|
||||
```
|
||||
|
||||
### 3. Relationship to bootc status
|
||||
|
||||
**Status Display**:
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Switch to new image
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Check updated status
|
||||
bootc status
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Image Validation Errors
|
||||
|
||||
```rust
|
||||
// Invalid transport
|
||||
Error: Invalid transport type 'invalid'
|
||||
|
||||
// Image not found
|
||||
Error: Image not found in registry
|
||||
|
||||
// Signature verification failed
|
||||
Error: Signature verification failed
|
||||
```
|
||||
|
||||
### 2. System State Errors
|
||||
|
||||
```rust
|
||||
// System not bootc compatible
|
||||
Error: System is not bootc compatible
|
||||
|
||||
// No changes detected
|
||||
Image specification is unchanged.
|
||||
|
||||
// Deployment not found
|
||||
Error: No deployment directory found
|
||||
```
|
||||
|
||||
### 3. Network and Registry Errors
|
||||
|
||||
```rust
|
||||
// Registry connectivity
|
||||
Error: Failed to connect to registry
|
||||
|
||||
// Authentication failed
|
||||
Error: Authentication failed
|
||||
|
||||
// Image pull failed
|
||||
Error: Failed to pull image
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Signature Verification
|
||||
|
||||
```bash
|
||||
# Enforce signature policy
|
||||
bootc switch --enforce-container-sigpolicy quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
**Purpose**: Ensure image authenticity and integrity
|
||||
**Requirements**: Valid signature policy in `/etc/containers/policy.json`
|
||||
|
||||
### 2. Transport Security
|
||||
|
||||
**Registry Transport**: Uses HTTPS and authentication
|
||||
**OCI Archive**: Local file system access
|
||||
**Containers Storage**: Local container storage
|
||||
|
||||
### 3. Image Validation
|
||||
|
||||
- **Schema Validation**: Validates image configuration
|
||||
- **Compatibility Check**: Ensures image is bootc-compatible
|
||||
- **Signature Verification**: Validates image signatures
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Image Pulling
|
||||
|
||||
- **Layer Caching**: Reuses existing layers when possible
|
||||
- **Incremental Updates**: Only downloads changed layers
|
||||
- **Parallel Downloads**: Downloads layers in parallel
|
||||
|
||||
### 2. Staging Process
|
||||
|
||||
- **Atomic Staging**: All-or-nothing staging process
|
||||
- **Rollback Capability**: Maintains previous deployment
|
||||
- **Status Updates**: Efficient status management
|
||||
|
||||
### 3. Disk Space Management
|
||||
|
||||
- **Reference Pruning**: Removes old image references by default
|
||||
- **Retention Option**: Keep references with `--retain`
|
||||
- **Cleanup**: Automatic cleanup of unused layers
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### Image Not Found
|
||||
```bash
|
||||
# Check image exists
|
||||
podman pull quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Check registry connectivity
|
||||
curl -I https://quay.io/v2/
|
||||
```
|
||||
|
||||
#### Signature Verification Failed
|
||||
```bash
|
||||
# Check signature policy
|
||||
cat /etc/containers/policy.json
|
||||
|
||||
# Verify image signatures
|
||||
podman inspect quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### System Not Compatible
|
||||
```bash
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check bootc compatibility
|
||||
bootc status --json | jq '.status.booted'
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Verify image
|
||||
podman inspect quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Image Management
|
||||
|
||||
- **Use Semantic Versioning**: Clear version numbering
|
||||
- **Test Before Switch**: Validate images in staging
|
||||
- **Monitor After Switch**: Watch for issues post-switch
|
||||
- **Keep Rollback Ready**: Maintain previous versions
|
||||
|
||||
### 2. Deployment Strategy
|
||||
|
||||
- **Blue/Green**: Use different image tags
|
||||
- **Canary Deployments**: Gradual rollout
|
||||
- **A/B Testing**: Compare different versions
|
||||
- **Emergency Procedures**: Quick rollback capability
|
||||
|
||||
### 3. Monitoring and Logging
|
||||
|
||||
- **Track Switch Operations**: Monitor journal logs
|
||||
- **Set Up Alerts**: Notify on switch failures
|
||||
- **Monitor System Health**: Watch for issues
|
||||
- **Document Changes**: Keep change records
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Userspace Restart**: For kernel-unchanged switches
|
||||
- **Rollback Automation**: Automatic rollback on failure
|
||||
- **Switch Scheduling**: Time-based switching
|
||||
- **Health Checks**: Pre/post switch validation
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for switching
|
||||
- **Web Interface**: Web-based image management
|
||||
- **Configuration Management**: Declarative switching
|
||||
- **Audit Logging**: Comprehensive audit trails
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc switch system's architecture, implementation, and usage patterns.
|
||||
467
upgrade/bootc-upgrade-guide.md
Normal file
467
upgrade/bootc-upgrade-guide.md
Normal file
|
|
@ -0,0 +1,467 @@
|
|||
# bootc upgrade - Comprehensive Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc upgrade` is the primary command for downloading and applying system updates in bootc-managed systems. It implements an A/B upgrade system where updates are staged and applied at the next boot, ensuring system stability and providing rollback capabilities.
|
||||
|
||||
## Purpose
|
||||
|
||||
The upgrade system serves several critical functions:
|
||||
|
||||
1. **Transactional Updates**: Downloads and stages updates without affecting the running system
|
||||
2. **A/B Deployment**: Maintains two system versions for safe rollback
|
||||
3. **Registry Integration**: Pulls updates from container registries
|
||||
4. **Automatic Application**: Can automatically apply updates and reboot
|
||||
5. **Soft Reboot Support**: Faster restarts when possible
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc upgrade [OPTIONS...]
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Check for available updates
|
||||
bootc upgrade --check
|
||||
|
||||
# Download and stage updates
|
||||
bootc upgrade
|
||||
|
||||
# Download, stage, and apply updates (with reboot)
|
||||
bootc upgrade --apply
|
||||
|
||||
# Upgrade with soft reboot if available
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
|
||||
# Quiet mode (no progress output)
|
||||
bootc upgrade --quiet
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
### Core Options
|
||||
|
||||
| Option | Description | Default | Conflicts With |
|
||||
|--------|-------------|---------|----------------|
|
||||
| `--check` | Check for updates without downloading | `false` | `--apply` |
|
||||
| `--apply` | Apply updates and reboot | `false` | `--check` |
|
||||
| `--quiet` | Suppress progress output | `false` | None |
|
||||
| `--soft-reboot` | Configure soft reboot behavior | `None` | `--check` |
|
||||
|
||||
### Soft Reboot Modes
|
||||
|
||||
| Mode | Description | Behavior |
|
||||
|------|-------------|----------|
|
||||
| `required` | Fail if soft reboot unavailable | Error if not supported |
|
||||
| `auto` | Use soft reboot if available | Fallback to regular reboot |
|
||||
|
||||
## Upgrade Process
|
||||
|
||||
### 1. Check Phase (`--check`)
|
||||
|
||||
The check phase only downloads metadata to determine if updates are available:
|
||||
|
||||
```bash
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Downloads container manifest and configuration
|
||||
- Compares with currently booted image
|
||||
- Shows available updates without downloading layers
|
||||
- Displays version information and digest
|
||||
|
||||
**Output example**:
|
||||
```
|
||||
Update available for: quay.io/myorg/debian-bootc:latest
|
||||
Version: 1.2.3
|
||||
Digest: sha256:abc123...
|
||||
```
|
||||
|
||||
### 2. Download Phase (default)
|
||||
|
||||
Downloads and stages the updated container image:
|
||||
|
||||
```bash
|
||||
bootc upgrade
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Downloads full container image layers
|
||||
- Stages the update for next boot
|
||||
- Preserves current running system
|
||||
- Updates system status
|
||||
|
||||
**Process**:
|
||||
1. **Registry Query**: Check for updated image
|
||||
2. **Layer Download**: Pull container layers
|
||||
3. **OSTree Import**: Convert to OSTree format
|
||||
4. **Staging**: Prepare for next boot
|
||||
5. **Status Update**: Mark as staged
|
||||
|
||||
### 3. Apply Phase (`--apply`)
|
||||
|
||||
Immediately applies staged updates and reboots:
|
||||
|
||||
```bash
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Applies staged updates
|
||||
- Reboots into new system
|
||||
- Preserves `/etc` and `/var` state
|
||||
- Updates bootloader configuration
|
||||
|
||||
## Upgrade Modes
|
||||
|
||||
### 1. Check-Only Mode
|
||||
|
||||
```bash
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Monitoring for updates
|
||||
- CI/CD pipeline checks
|
||||
- Update availability verification
|
||||
- Automated update detection
|
||||
|
||||
**Benefits**:
|
||||
- Fast execution (metadata only)
|
||||
- No bandwidth usage for full download
|
||||
- Safe to run frequently
|
||||
|
||||
### 2. Stage-Only Mode
|
||||
|
||||
```bash
|
||||
bootc upgrade
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Download updates for later application
|
||||
- Batch update preparation
|
||||
- Offline update preparation
|
||||
- Manual control over application timing
|
||||
|
||||
**Benefits**:
|
||||
- Updates ready for next boot
|
||||
- No immediate system changes
|
||||
- Allows review before application
|
||||
|
||||
### 3. Immediate Apply Mode
|
||||
|
||||
```bash
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Automated update application
|
||||
- CI/CD deployment
|
||||
- Immediate update application
|
||||
- Single-command updates
|
||||
|
||||
**Benefits**:
|
||||
- Complete update cycle
|
||||
- Automatic reboot
|
||||
- No manual intervention required
|
||||
|
||||
## Soft Reboot Support
|
||||
|
||||
### What is Soft Reboot?
|
||||
|
||||
Soft reboot is a faster restart mechanism that avoids full hardware reboot when possible, typically used in virtualized environments.
|
||||
|
||||
### Soft Reboot Modes
|
||||
|
||||
#### Required Mode
|
||||
```bash
|
||||
bootc upgrade --apply --soft-reboot=required
|
||||
```
|
||||
|
||||
**Behavior**:
|
||||
- Fails if soft reboot is not available
|
||||
- Ensures fastest possible restart
|
||||
- Use when soft reboot is critical
|
||||
|
||||
#### Auto Mode
|
||||
```bash
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
```
|
||||
|
||||
**Behavior**:
|
||||
- Uses soft reboot if available
|
||||
- Falls back to regular reboot if not supported
|
||||
- Recommended for most use cases
|
||||
|
||||
### Soft Reboot Requirements
|
||||
|
||||
- Virtualized environment (VMware, QEMU, etc.)
|
||||
- Kernel support for kexec
|
||||
- Sufficient memory for kexec
|
||||
- Compatible hardware
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### 1. Manual Updates
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# If updates available, apply them
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### 2. Automated Updates
|
||||
|
||||
```bash
|
||||
# Automated update with soft reboot
|
||||
bootc upgrade --apply --soft-reboot=auto --quiet
|
||||
```
|
||||
|
||||
### 3. CI/CD Integration
|
||||
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
- name: Update system
|
||||
run: |
|
||||
bootc upgrade --check
|
||||
if [ $? -eq 0 ]; then
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
fi
|
||||
```
|
||||
|
||||
### 4. Monitoring Integration
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Update monitoring script
|
||||
if bootc upgrade --check; then
|
||||
echo "Updates available"
|
||||
# Send notification
|
||||
notify-send "System updates available"
|
||||
else
|
||||
echo "System up to date"
|
||||
fi
|
||||
```
|
||||
|
||||
## Status and Monitoring
|
||||
|
||||
### Check Update Status
|
||||
|
||||
```bash
|
||||
# View current status
|
||||
bootc status
|
||||
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
### Status Indicators
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `booted` | Currently running system |
|
||||
| `staged` | Update ready for next boot |
|
||||
| `incompatible` | System has local modifications |
|
||||
|
||||
### Update Verification
|
||||
|
||||
```bash
|
||||
# Check what's staged
|
||||
bootc status
|
||||
|
||||
# Verify update details
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
## Rollback and Recovery
|
||||
|
||||
### Rollback Process
|
||||
|
||||
```bash
|
||||
# Rollback to previous version
|
||||
bootc rollback
|
||||
|
||||
# Check rollback status
|
||||
bootc status
|
||||
```
|
||||
|
||||
### Recovery Scenarios
|
||||
|
||||
1. **Failed Update**: Use `bootc rollback`
|
||||
2. **Corrupted System**: Boot from previous deployment
|
||||
3. **Incompatible Update**: Check system compatibility
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Update Strategy
|
||||
|
||||
- **Test First**: Test updates in staging environment
|
||||
- **Gradual Rollout**: Use `bootc switch` for controlled deployments
|
||||
- **Monitor Status**: Check `bootc status` regularly
|
||||
- **Backup State**: Ensure `/etc` and `/var` are backed up
|
||||
|
||||
### 2. Automation
|
||||
|
||||
- **Use `--check`**: For monitoring and CI/CD
|
||||
- **Use `--apply`**: For automated deployments
|
||||
- **Use `--soft-reboot`**: For faster restarts when possible
|
||||
- **Use `--quiet`**: For automated scripts
|
||||
|
||||
### 3. Error Handling
|
||||
|
||||
- **Check Return Codes**: Handle update failures gracefully
|
||||
- **Verify Status**: Confirm updates are staged correctly
|
||||
- **Test Rollback**: Ensure rollback works before applying
|
||||
- **Monitor Logs**: Check system logs for issues
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### No Updates Available
|
||||
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Verify image source
|
||||
bootc edit
|
||||
|
||||
# Check registry connectivity
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
#### Update Fails to Apply
|
||||
|
||||
```bash
|
||||
# Check staged status
|
||||
bootc status
|
||||
|
||||
# Verify system compatibility
|
||||
bootc upgrade --check
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### Soft Reboot Fails
|
||||
|
||||
```bash
|
||||
# Check soft reboot support
|
||||
bootc upgrade --apply --soft-reboot=required
|
||||
|
||||
# Fall back to regular reboot
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc upgrade --check
|
||||
|
||||
# Check system status
|
||||
bootc status --json
|
||||
|
||||
# Verify image integrity
|
||||
bootc upgrade --check --quiet
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### 1. Custom Image Sources
|
||||
|
||||
```bash
|
||||
# Switch to different image
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Upgrade from new source
|
||||
bootc upgrade
|
||||
```
|
||||
|
||||
### 2. Offline Updates
|
||||
|
||||
```bash
|
||||
# Download updates offline
|
||||
bootc upgrade
|
||||
|
||||
# Apply when ready
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### 3. Batch Updates
|
||||
|
||||
```bash
|
||||
# Download multiple updates
|
||||
bootc upgrade
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.1
|
||||
bootc upgrade
|
||||
|
||||
# Apply all at once
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Image Verification
|
||||
|
||||
- **Signature Verification**: Ensure images are signed
|
||||
- **Registry Security**: Use trusted registries
|
||||
- **Digest Verification**: Verify image digests
|
||||
|
||||
### 2. Update Security
|
||||
|
||||
- **Network Security**: Use secure connections
|
||||
- **Authentication**: Authenticate with registries
|
||||
- **Authorization**: Control update permissions
|
||||
|
||||
### 3. Rollback Security
|
||||
|
||||
- **State Preservation**: Ensure `/etc` and `/var` are secure
|
||||
- **Access Control**: Limit rollback permissions
|
||||
- **Audit Logging**: Log all update activities
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### 1. Update Speed
|
||||
|
||||
- **Use `--check`**: For quick availability checks
|
||||
- **Use `--soft-reboot`**: For faster restarts
|
||||
- **Use `--quiet`**: For automated scripts
|
||||
|
||||
### 2. Bandwidth Usage
|
||||
|
||||
- **Check First**: Use `--check` before downloading
|
||||
- **Incremental Updates**: Only download changed layers
|
||||
- **Local Caching**: Use local registry mirrors
|
||||
|
||||
### 3. System Impact
|
||||
|
||||
- **Staged Updates**: No impact on running system
|
||||
- **Atomic Application**: All-or-nothing updates
|
||||
- **Rollback Capability**: Quick recovery from issues
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Userspace Restart**: For kernel-unchanged updates
|
||||
- **Delta Updates**: More efficient layer downloads
|
||||
- **Rollback Automation**: Automatic rollback on failure
|
||||
- **Update Scheduling**: Time-based update application
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for update management
|
||||
- **Webhook Integration**: Event notifications
|
||||
- **Metrics Collection**: Update performance metrics
|
||||
- **Dashboard Integration**: Web-based management
|
||||
|
||||
---
|
||||
|
||||
This comprehensive guide provides everything needed to understand and use `bootc upgrade` effectively for system updates and maintenance.
|
||||
662
upgrade/examples-and-troubleshooting.md
Normal file
662
upgrade/examples-and-troubleshooting.md
Normal file
|
|
@ -0,0 +1,662 @@
|
|||
# bootc upgrade - Examples and Troubleshooting
|
||||
|
||||
## Practical Examples
|
||||
|
||||
### 1. Basic Update Operations
|
||||
|
||||
#### Check for Updates
|
||||
|
||||
```bash
|
||||
# Check if updates are available
|
||||
bootc upgrade --check
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
```
|
||||
|
||||
#### Download Updates
|
||||
|
||||
```bash
|
||||
# Download and stage updates
|
||||
bootc upgrade
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
# Staging update...
|
||||
# Update staged successfully
|
||||
```
|
||||
|
||||
#### Apply Updates
|
||||
|
||||
```bash
|
||||
# Apply updates and reboot
|
||||
bootc upgrade --apply
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
# Staging update...
|
||||
# Update staged successfully
|
||||
# Rebooting system...
|
||||
```
|
||||
|
||||
### 2. Automated Update Scripts
|
||||
|
||||
#### Simple Update Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# update-system.sh
|
||||
|
||||
set -e
|
||||
|
||||
echo "Checking for updates..."
|
||||
if bootc upgrade --check; then
|
||||
echo "Updates available, applying..."
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
else
|
||||
echo "System is up to date"
|
||||
fi
|
||||
```
|
||||
|
||||
#### Advanced Update Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# advanced-update.sh
|
||||
|
||||
set -e
|
||||
|
||||
# Configuration
|
||||
IMAGE_SOURCE="quay.io/myorg/debian-bootc:latest"
|
||||
LOG_FILE="/var/log/bootc-updates.log"
|
||||
MAX_RETRIES=3
|
||||
|
||||
# Logging function
|
||||
log() {
|
||||
echo "$(date): $1" | tee -a "$LOG_FILE"
|
||||
}
|
||||
|
||||
# Update function
|
||||
update_system() {
|
||||
local retry_count=0
|
||||
|
||||
while [ $retry_count -lt $MAX_RETRIES ]; do
|
||||
log "Attempting update (attempt $((retry_count + 1)))"
|
||||
|
||||
if bootc upgrade --check; then
|
||||
log "Updates available, applying..."
|
||||
if bootc upgrade --apply --soft-reboot=auto; then
|
||||
log "Update applied successfully"
|
||||
return 0
|
||||
else
|
||||
log "Update failed, retrying..."
|
||||
retry_count=$((retry_count + 1))
|
||||
sleep 30
|
||||
fi
|
||||
else
|
||||
log "No updates available"
|
||||
return 0
|
||||
fi
|
||||
done
|
||||
|
||||
log "Update failed after $MAX_RETRIES attempts"
|
||||
return 1
|
||||
}
|
||||
|
||||
# Main execution
|
||||
log "Starting update process"
|
||||
update_system
|
||||
log "Update process completed"
|
||||
```
|
||||
|
||||
### 3. CI/CD Integration
|
||||
|
||||
#### GitHub Actions
|
||||
|
||||
```yaml
|
||||
name: Update System
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 2 * * *' # Daily at 2 AM
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
update:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup SSH
|
||||
uses: webfactory/ssh-agent@v0.7.0
|
||||
with:
|
||||
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
|
||||
|
||||
- name: Update System
|
||||
run: |
|
||||
ssh -o StrictHostKeyChecking=no user@${{ secrets.HOST_IP }} '
|
||||
bootc upgrade --check
|
||||
if [ $? -eq 0 ]; then
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
fi
|
||||
'
|
||||
```
|
||||
|
||||
#### GitLab CI
|
||||
|
||||
```yaml
|
||||
stages:
|
||||
- update
|
||||
|
||||
update_system:
|
||||
stage: update
|
||||
script:
|
||||
- ssh user@$HOST_IP 'bootc upgrade --check'
|
||||
- ssh user@$HOST_IP 'bootc upgrade --apply --soft-reboot=auto'
|
||||
only:
|
||||
- schedules
|
||||
- web
|
||||
```
|
||||
|
||||
#### Jenkins Pipeline
|
||||
|
||||
```groovy
|
||||
pipeline {
|
||||
agent any
|
||||
|
||||
stages {
|
||||
stage('Update System') {
|
||||
steps {
|
||||
script {
|
||||
sh '''
|
||||
ssh user@${HOST_IP} 'bootc upgrade --check'
|
||||
if [ $? -eq 0 ]; then
|
||||
ssh user@${HOST_IP} 'bootc upgrade --apply --soft-reboot=auto'
|
||||
fi
|
||||
'''
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
triggers {
|
||||
cron('0 2 * * *') // Daily at 2 AM
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Monitoring and Alerting
|
||||
|
||||
#### Update Monitoring Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# monitor-updates.sh
|
||||
|
||||
# Configuration
|
||||
WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
|
||||
HOSTNAME=$(hostname)
|
||||
|
||||
# Check for updates
|
||||
check_updates() {
|
||||
if bootc upgrade --check > /dev/null 2>&1; then
|
||||
return 0 # Updates available
|
||||
else
|
||||
return 1 # No updates
|
||||
fi
|
||||
}
|
||||
|
||||
# Send notification
|
||||
send_notification() {
|
||||
local message="$1"
|
||||
curl -X POST -H 'Content-type: application/json' \
|
||||
--data "{\"text\":\"$HOSTNAME: $message\"}" \
|
||||
"$WEBHOOK_URL"
|
||||
}
|
||||
|
||||
# Main monitoring loop
|
||||
while true; do
|
||||
if check_updates; then
|
||||
send_notification "Updates available for $HOSTNAME"
|
||||
# Wait longer after finding updates
|
||||
sleep 3600 # 1 hour
|
||||
else
|
||||
# Check more frequently when no updates
|
||||
sleep 300 # 5 minutes
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
#### Prometheus Metrics
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# prometheus-metrics.sh
|
||||
|
||||
# Create metrics file
|
||||
METRICS_FILE="/var/lib/prometheus/node-exporter/bootc-updates.prom"
|
||||
|
||||
# Check update status
|
||||
if bootc upgrade --check > /dev/null 2>&1; then
|
||||
UPDATES_AVAILABLE=1
|
||||
else
|
||||
UPDATES_AVAILABLE=0
|
||||
fi
|
||||
|
||||
# Write metrics
|
||||
cat > "$METRICS_FILE" << EOF
|
||||
# HELP bootc_updates_available Whether updates are available
|
||||
# TYPE bootc_updates_available gauge
|
||||
bootc_updates_available $UPDATES_AVAILABLE
|
||||
EOF
|
||||
```
|
||||
|
||||
### 5. Systemd Integration
|
||||
|
||||
#### Update Service
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/bootc-update.service
|
||||
[Unit]
|
||||
Description=Update bootc system
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/bin/update-system.sh
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
#### Update Timer
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/bootc-update.timer
|
||||
[Unit]
|
||||
Description=Update bootc system daily
|
||||
Requires=bootc-update.service
|
||||
|
||||
[Timer]
|
||||
OnCalendar=daily
|
||||
Persistent=true
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
```
|
||||
|
||||
#### Enable and Start
|
||||
|
||||
```bash
|
||||
# Enable and start timer
|
||||
sudo systemctl enable bootc-update.timer
|
||||
sudo systemctl start bootc-update.timer
|
||||
|
||||
# Check status
|
||||
sudo systemctl status bootc-update.timer
|
||||
sudo systemctl list-timers bootc-update.timer
|
||||
```
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### No Updates Available
|
||||
|
||||
**Problem**: `bootc upgrade --check` shows no updates
|
||||
**Possible Causes**:
|
||||
- System is already up to date
|
||||
- Registry connectivity issues
|
||||
- Image source not configured
|
||||
- Authentication problems
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Verify image source
|
||||
bootc edit
|
||||
|
||||
# Test registry connectivity
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Check authentication
|
||||
podman login quay.io
|
||||
```
|
||||
|
||||
#### Update Fails to Download
|
||||
|
||||
**Problem**: `bootc upgrade` fails during download
|
||||
**Possible Causes**:
|
||||
- Network connectivity issues
|
||||
- Registry authentication problems
|
||||
- Insufficient disk space
|
||||
- Registry rate limiting
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check network connectivity
|
||||
ping quay.io
|
||||
|
||||
# Check disk space
|
||||
df -h
|
||||
|
||||
# Check authentication
|
||||
podman login quay.io
|
||||
|
||||
# Retry with verbose output
|
||||
RUST_LOG=debug bootc upgrade
|
||||
```
|
||||
|
||||
#### Update Fails to Apply
|
||||
|
||||
**Problem**: `bootc upgrade --apply` fails
|
||||
**Possible Causes**:
|
||||
- Staged update corrupted
|
||||
- Insufficient disk space
|
||||
- Bootloader configuration issues
|
||||
- System compatibility problems
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check staged status
|
||||
bootc status
|
||||
|
||||
# Verify system compatibility
|
||||
bootc upgrade --check
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Try rollback
|
||||
bootc rollback
|
||||
```
|
||||
|
||||
#### Soft Reboot Fails
|
||||
|
||||
**Problem**: `--soft-reboot=required` fails
|
||||
**Possible Causes**:
|
||||
- Soft reboot not supported
|
||||
- Insufficient memory
|
||||
- Kernel compatibility issues
|
||||
- Hardware limitations
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check soft reboot support
|
||||
bootc upgrade --apply --soft-reboot=required
|
||||
|
||||
# Use auto mode (fallback to regular reboot)
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
|
||||
# Use regular reboot
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
#### Enable Debug Logging
|
||||
|
||||
```bash
|
||||
# Enable debug output
|
||||
RUST_LOG=debug bootc upgrade --check
|
||||
|
||||
# Enable trace output
|
||||
RUST_LOG=trace bootc upgrade --check
|
||||
|
||||
# Save debug output to file
|
||||
RUST_LOG=debug bootc upgrade --check 2>&1 | tee debug.log
|
||||
```
|
||||
|
||||
#### Check System Status
|
||||
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Check status in JSON format
|
||||
bootc status --json
|
||||
|
||||
# Check system configuration
|
||||
bootc edit
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### Verify Image Integrity
|
||||
|
||||
```bash
|
||||
# Check image source
|
||||
bootc edit
|
||||
|
||||
# Verify image exists
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Check image labels
|
||||
podman inspect quay.io/myorg/debian-bootc:latest | jq '.[0].Config.Labels'
|
||||
```
|
||||
|
||||
### 3. Recovery Procedures
|
||||
|
||||
#### Rollback from Failed Update
|
||||
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Rollback to previous version
|
||||
bootc rollback
|
||||
|
||||
# Verify rollback
|
||||
bootc status
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### Reset System State
|
||||
|
||||
```bash
|
||||
# Check for local modifications
|
||||
bootc status
|
||||
|
||||
# Reset local modifications (if any)
|
||||
rpm-ostree reset
|
||||
|
||||
# Check status again
|
||||
bootc status
|
||||
|
||||
# Try update again
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
#### Manual Image Switch
|
||||
|
||||
```bash
|
||||
# Switch to different image
|
||||
bootc switch quay.io/myorg/debian-bootc:v1.0
|
||||
|
||||
# Check status
|
||||
bootc status
|
||||
|
||||
# Apply update
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### 4. Performance Issues
|
||||
|
||||
#### Slow Update Downloads
|
||||
|
||||
**Problem**: Updates take too long to download
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check network speed
|
||||
speedtest-cli
|
||||
|
||||
# Use local registry mirror
|
||||
bootc switch registry.local/myorg/debian-bootc:latest
|
||||
|
||||
# Check disk I/O
|
||||
iostat -x 1
|
||||
|
||||
# Use quiet mode
|
||||
bootc upgrade --quiet
|
||||
```
|
||||
|
||||
#### High Memory Usage
|
||||
|
||||
**Problem**: Update process uses too much memory
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check memory usage
|
||||
free -h
|
||||
|
||||
# Check swap usage
|
||||
swapon -s
|
||||
|
||||
# Monitor during update
|
||||
htop
|
||||
|
||||
# Use check mode first
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
#### Disk Space Issues
|
||||
|
||||
**Problem**: Insufficient disk space for updates
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check disk usage
|
||||
df -h
|
||||
|
||||
# Clean up old deployments
|
||||
ostree admin cleanup
|
||||
|
||||
# Check OSTree usage
|
||||
ostree admin status
|
||||
|
||||
# Free up space
|
||||
sudo apt autoremove
|
||||
sudo apt autoclean
|
||||
```
|
||||
|
||||
### 5. Network Issues
|
||||
|
||||
#### Registry Connectivity
|
||||
|
||||
**Problem**: Cannot connect to registry
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Test connectivity
|
||||
ping quay.io
|
||||
|
||||
# Check DNS resolution
|
||||
nslookup quay.io
|
||||
|
||||
# Test with curl
|
||||
curl -I https://quay.io
|
||||
|
||||
# Check firewall
|
||||
sudo ufw status
|
||||
```
|
||||
|
||||
#### Authentication Issues
|
||||
|
||||
**Problem**: Registry authentication fails
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Login to registry
|
||||
podman login quay.io
|
||||
|
||||
# Check credentials
|
||||
cat ~/.docker/config.json
|
||||
|
||||
# Test authentication
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Check token expiration
|
||||
podman logout quay.io
|
||||
podman login quay.io
|
||||
```
|
||||
|
||||
#### Proxy Configuration
|
||||
|
||||
**Problem**: Updates fail behind proxy
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Configure proxy for podman
|
||||
mkdir -p ~/.config/containers
|
||||
cat > ~/.config/containers/containers.conf << EOF
|
||||
[containers]
|
||||
http_proxy = "http://proxy.example.com:8080"
|
||||
https_proxy = "http://proxy.example.com:8080"
|
||||
no_proxy = "localhost,127.0.0.1"
|
||||
EOF
|
||||
|
||||
# Test proxy
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
### 6. Advanced Troubleshooting
|
||||
|
||||
#### System Logs Analysis
|
||||
|
||||
```bash
|
||||
# Check bootc logs
|
||||
journalctl -u bootc-fetch-apply-updates.service -f
|
||||
|
||||
# Check system logs
|
||||
journalctl -f
|
||||
|
||||
# Check kernel logs
|
||||
dmesg | tail -50
|
||||
|
||||
# Check boot logs
|
||||
journalctl -b
|
||||
```
|
||||
|
||||
#### Network Diagnostics
|
||||
|
||||
```bash
|
||||
# Check network interfaces
|
||||
ip addr show
|
||||
|
||||
# Check routing table
|
||||
ip route show
|
||||
|
||||
# Check DNS configuration
|
||||
cat /etc/resolv.conf
|
||||
|
||||
# Test DNS resolution
|
||||
dig quay.io
|
||||
```
|
||||
|
||||
#### System Health Check
|
||||
|
||||
```bash
|
||||
# Check system resources
|
||||
htop
|
||||
|
||||
# Check disk health
|
||||
sudo smartctl -a /dev/sda
|
||||
|
||||
# Check memory
|
||||
free -h
|
||||
|
||||
# Check CPU
|
||||
lscpu
|
||||
```
|
||||
|
||||
This comprehensive examples and troubleshooting guide provides practical solutions for common bootc upgrade issues and integration patterns.
|
||||
857
upgrade/external-commands-reference.md
Normal file
857
upgrade/external-commands-reference.md
Normal file
|
|
@ -0,0 +1,857 @@
|
|||
# bootc upgrade - 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 upgrade` system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc upgrades into larger systems.
|
||||
|
||||
## Core System Commands
|
||||
|
||||
### 1. bootc Commands
|
||||
|
||||
#### bootc upgrade
|
||||
**Purpose**: Primary upgrade command
|
||||
**Usage**: `bootc upgrade [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment management
|
||||
- `podman` - For container registry access
|
||||
- `systemd` - For service management and reboot
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# Download and stage updates
|
||||
bootc upgrade
|
||||
|
||||
# Apply updates and reboot
|
||||
bootc upgrade --apply
|
||||
|
||||
# Apply with soft reboot
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
```
|
||||
|
||||
#### 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 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
|
||||
```
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
### 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 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
|
||||
```
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### 4. System Management Commands
|
||||
|
||||
#### systemctl
|
||||
**Purpose**: Control systemd services and units
|
||||
**Usage**: `systemctl [COMMAND] [UNIT...]`
|
||||
**Integration**: Used for service management and reboot coordination
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-fetch-apply-updates.service
|
||||
|
||||
# Start service
|
||||
systemctl start bootc-fetch-apply-updates.service
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-fetch-apply-updates.service
|
||||
|
||||
# Restart service
|
||||
systemctl restart bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### reboot
|
||||
**Purpose**: Reboot the system
|
||||
**Usage**: `reboot [OPTIONS...]`
|
||||
**Integration**: Used by `bootc upgrade --apply` for system restart
|
||||
|
||||
```bash
|
||||
# Reboot system
|
||||
reboot
|
||||
|
||||
# Reboot with specific delay
|
||||
reboot +5
|
||||
|
||||
# Reboot with message
|
||||
reboot "Applying bootc update"
|
||||
```
|
||||
|
||||
#### shutdown
|
||||
**Purpose**: Shutdown the system
|
||||
**Usage**: `shutdown [OPTIONS...]`
|
||||
**Integration**: Used for controlled shutdown before reboot
|
||||
|
||||
```bash
|
||||
# Shutdown system
|
||||
shutdown -h now
|
||||
|
||||
# Shutdown with delay
|
||||
shutdown -h +5
|
||||
|
||||
# Shutdown with message
|
||||
shutdown -h now "Applying bootc update"
|
||||
```
|
||||
|
||||
## System Services
|
||||
|
||||
### 1. bootc-fetch-apply-updates.service
|
||||
|
||||
**Purpose**: Automated update fetching and application
|
||||
**File**: `/usr/lib/systemd/system/bootc-fetch-apply-updates.service`
|
||||
**Dependencies**:
|
||||
- `network-online.target`
|
||||
- `bootc` command
|
||||
- `ostree` system
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Download and apply bootc updates
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/bin/bootc upgrade --apply
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
**Management Commands**:
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-fetch-apply-updates.service
|
||||
|
||||
# Start service manually
|
||||
systemctl start bootc-fetch-apply-updates.service
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-fetch-apply-updates.service
|
||||
|
||||
# Check service logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
### 2. bootc-fetch-apply-updates.timer
|
||||
|
||||
**Purpose**: Schedule automated updates
|
||||
**File**: `/usr/lib/systemd/system/bootc-fetch-apply-updates.timer`
|
||||
**Dependencies**:
|
||||
- `bootc-fetch-apply-updates.service`
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Download and apply bootc updates daily
|
||||
Requires=bootc-fetch-apply-updates.service
|
||||
|
||||
[Timer]
|
||||
OnCalendar=daily
|
||||
Persistent=true
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
```
|
||||
|
||||
**Management Commands**:
|
||||
```bash
|
||||
# Check timer status
|
||||
systemctl status bootc-fetch-apply-updates.timer
|
||||
|
||||
# List timers
|
||||
systemctl list-timers bootc-fetch-apply-updates.timer
|
||||
|
||||
# Start timer
|
||||
systemctl start bootc-fetch-apply-updates.timer
|
||||
|
||||
# Enable timer
|
||||
systemctl enable bootc-fetch-apply-updates.timer
|
||||
```
|
||||
|
||||
### 3. ostree-finalize-staged.service
|
||||
|
||||
**Purpose**: Finalize staged OSTree deployments
|
||||
**File**: `/usr/lib/systemd/system/ostree-finalize-staged.service`
|
||||
**Dependencies**:
|
||||
- `ostree` system
|
||||
- `systemd` reboot coordination
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Finalize staged OSTree deployment
|
||||
After=ostree-remount.service
|
||||
Before=systemd-reboot.service
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/bin/ostree admin finalize-staged
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
**Management Commands**:
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status ostree-finalize-staged.service
|
||||
|
||||
# Check service logs
|
||||
journalctl -u ostree-finalize-staged.service
|
||||
|
||||
# Manually run service
|
||||
systemctl start ostree-finalize-staged.service
|
||||
```
|
||||
|
||||
## Network and Registry Commands
|
||||
|
||||
### 1. curl
|
||||
**Purpose**: HTTP client for registry communication
|
||||
**Usage**: `curl [OPTIONS...] URL`
|
||||
**Integration**: Used for registry API calls and authentication
|
||||
|
||||
```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
|
||||
|
||||
# Authenticate with registry
|
||||
curl -u username:password https://quay.io/v2/token
|
||||
```
|
||||
|
||||
### 2. 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
|
||||
```
|
||||
|
||||
### 3. 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
|
||||
```
|
||||
|
||||
### 4. 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
|
||||
```
|
||||
|
||||
## Storage and Filesystem Commands
|
||||
|
||||
### 1. 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
|
||||
```
|
||||
|
||||
### 2. du
|
||||
**Purpose**: Display directory space usage
|
||||
**Usage**: `du [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for directory space analysis
|
||||
|
||||
```bash
|
||||
# Check directory usage
|
||||
du -sh /sysroot
|
||||
|
||||
# Check OSTree usage
|
||||
du -sh /sysroot/ostree
|
||||
|
||||
# Check specific deployment
|
||||
du -sh /sysroot/ostree/deploy/debian-bootc
|
||||
```
|
||||
|
||||
### 3. lsblk
|
||||
**Purpose**: List block devices
|
||||
**Usage**: `lsblk [OPTIONS...]`
|
||||
**Integration**: Used for storage device identification
|
||||
|
||||
```bash
|
||||
# List all block devices
|
||||
lsblk
|
||||
|
||||
# List with filesystem information
|
||||
lsblk -f
|
||||
|
||||
# List specific device
|
||||
lsblk /dev/sda
|
||||
```
|
||||
|
||||
### 4. mount
|
||||
**Purpose**: Mount filesystems
|
||||
**Usage**: `mount [OPTIONS...] DEVICE DIR`
|
||||
**Integration**: Used for filesystem mounting
|
||||
|
||||
```bash
|
||||
# List mounted filesystems
|
||||
mount
|
||||
|
||||
# Mount specific device
|
||||
mount /dev/sda1 /mnt
|
||||
|
||||
# Mount with options
|
||||
mount -o ro /dev/sda1 /mnt
|
||||
```
|
||||
|
||||
## Monitoring and Logging Commands
|
||||
|
||||
### 1. 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
|
||||
```
|
||||
|
||||
### 2. 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
|
||||
```
|
||||
|
||||
### 3. 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)
|
||||
```
|
||||
|
||||
### 4. iostat
|
||||
**Purpose**: I/O statistics
|
||||
**Usage**: `iostat [OPTIONS...]`
|
||||
**Integration**: Used for disk I/O monitoring
|
||||
|
||||
```bash
|
||||
# Display I/O statistics
|
||||
iostat
|
||||
|
||||
# Display with interval
|
||||
iostat 1
|
||||
|
||||
# Display specific device
|
||||
iostat /dev/sda
|
||||
```
|
||||
|
||||
## Security and Authentication Commands
|
||||
|
||||
### 1. 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
|
||||
|
||||
# Generate key pair
|
||||
openssl genrsa -out private.key 2048
|
||||
```
|
||||
|
||||
### 2. gpg
|
||||
**Purpose**: GNU Privacy Guard
|
||||
**Usage**: `gpg [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Used for signature verification
|
||||
|
||||
```bash
|
||||
# Verify signature
|
||||
gpg --verify signature.asc file.txt
|
||||
|
||||
# Import public key
|
||||
gpg --import public.key
|
||||
|
||||
# List keys
|
||||
gpg --list-keys
|
||||
```
|
||||
|
||||
### 3. ssh
|
||||
**Purpose**: Secure shell client
|
||||
**Usage**: `ssh [OPTIONS...] [USER@]HOST [COMMAND]`
|
||||
**Integration**: Used for remote system management
|
||||
|
||||
```bash
|
||||
# Connect to remote system
|
||||
ssh user@hostname
|
||||
|
||||
# Execute remote command
|
||||
ssh user@hostname 'bootc upgrade --check'
|
||||
|
||||
# Copy files
|
||||
scp file.txt user@hostname:/path/to/destination
|
||||
```
|
||||
|
||||
## Network Troubleshooting Commands
|
||||
|
||||
### 1. ping
|
||||
**Purpose**: Test network connectivity
|
||||
**Usage**: `ping [OPTIONS...] HOST`
|
||||
**Integration**: Used for network connectivity testing
|
||||
|
||||
```bash
|
||||
# Test connectivity
|
||||
ping quay.io
|
||||
|
||||
# Test with specific count
|
||||
ping -c 4 quay.io
|
||||
|
||||
# Test with specific interface
|
||||
ping -I eth0 quay.io
|
||||
```
|
||||
|
||||
### 2. traceroute
|
||||
**Purpose**: Trace network path
|
||||
**Usage**: `traceroute [OPTIONS...] HOST`
|
||||
**Integration**: Used for network path analysis
|
||||
|
||||
```bash
|
||||
# Trace path to registry
|
||||
traceroute quay.io
|
||||
|
||||
# Trace with specific options
|
||||
traceroute -n quay.io
|
||||
```
|
||||
|
||||
### 3. netstat
|
||||
**Purpose**: Display network connections
|
||||
**Usage**: `netstat [OPTIONS...]`
|
||||
**Integration**: Used for network connection analysis
|
||||
|
||||
```bash
|
||||
# Display all connections
|
||||
netstat -an
|
||||
|
||||
# Display listening ports
|
||||
netstat -ln
|
||||
|
||||
# Display with process information
|
||||
netstat -tulpn
|
||||
```
|
||||
|
||||
### 4. ss
|
||||
**Purpose**: Socket statistics
|
||||
**Usage**: `ss [OPTIONS...]`
|
||||
**Integration**: Modern alternative to netstat
|
||||
|
||||
```bash
|
||||
# Display all sockets
|
||||
ss -an
|
||||
|
||||
# Display listening sockets
|
||||
ss -ln
|
||||
|
||||
# Display with process information
|
||||
ss -tulpn
|
||||
```
|
||||
|
||||
## Container Runtime Commands
|
||||
|
||||
### 1. podman
|
||||
**Purpose**: Container runtime
|
||||
**Usage**: `podman [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Primary container runtime for bootc
|
||||
|
||||
```bash
|
||||
# List containers
|
||||
podman ps -a
|
||||
|
||||
# List images
|
||||
podman images
|
||||
|
||||
# Run container
|
||||
podman run -it quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Remove containers
|
||||
podman rm -f container-id
|
||||
```
|
||||
|
||||
### 2. docker
|
||||
**Purpose**: Alternative container runtime
|
||||
**Usage**: `docker [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Alternative to podman
|
||||
|
||||
```bash
|
||||
# List containers
|
||||
docker ps -a
|
||||
|
||||
# List images
|
||||
docker images
|
||||
|
||||
# Run container
|
||||
docker run -it quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
## System Information Commands
|
||||
|
||||
### 1. 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
|
||||
```
|
||||
|
||||
### 2. lscpu
|
||||
**Purpose**: Display CPU information
|
||||
**Usage**: `lscpu [OPTIONS...]`
|
||||
**Integration**: Used for system resource analysis
|
||||
|
||||
```bash
|
||||
# Display CPU information
|
||||
lscpu
|
||||
|
||||
# Display in specific format
|
||||
lscpu --extended
|
||||
```
|
||||
|
||||
### 3. 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
|
||||
```
|
||||
|
||||
### 4. uptime
|
||||
**Purpose**: Display system uptime
|
||||
**Usage**: `uptime [OPTIONS...]`
|
||||
**Integration**: Used for system status monitoring
|
||||
|
||||
```bash
|
||||
# Display uptime
|
||||
uptime
|
||||
|
||||
# Display with load average
|
||||
uptime -p
|
||||
```
|
||||
|
||||
## Configuration Management Commands
|
||||
|
||||
### 1. bootc edit
|
||||
**Purpose**: Edit bootc configuration
|
||||
**Usage**: `bootc edit [OPTIONS...]`
|
||||
**Integration**: Used for configuration management
|
||||
|
||||
```bash
|
||||
# Edit configuration
|
||||
bootc edit
|
||||
|
||||
# Edit specific deployment
|
||||
bootc edit --deployment=deployment-id
|
||||
```
|
||||
|
||||
### 2. bootc config
|
||||
**Purpose**: Display bootc configuration
|
||||
**Usage**: `bootc config [OPTIONS...]`
|
||||
**Integration**: Used for configuration inspection
|
||||
|
||||
```bash
|
||||
# Display configuration
|
||||
bootc config
|
||||
|
||||
# Display in specific format
|
||||
bootc config --json
|
||||
```
|
||||
|
||||
## Backup and Recovery Commands
|
||||
|
||||
### 1. tar
|
||||
**Purpose**: Archive files
|
||||
**Usage**: `tar [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for backup creation
|
||||
|
||||
```bash
|
||||
# Create backup
|
||||
tar -czf backup.tar.gz /sysroot
|
||||
|
||||
# Extract backup
|
||||
tar -xzf backup.tar.gz
|
||||
|
||||
# List archive contents
|
||||
tar -tzf backup.tar.gz
|
||||
```
|
||||
|
||||
### 2. rsync
|
||||
**Purpose**: Synchronize files
|
||||
**Usage**: `rsync [OPTIONS...] SRC DEST`
|
||||
**Integration**: Used for backup synchronization
|
||||
|
||||
```bash
|
||||
# Synchronize files
|
||||
rsync -av /sysroot/ /backup/sysroot/
|
||||
|
||||
# Synchronize with remote
|
||||
rsync -av /sysroot/ user@host:/backup/sysroot/
|
||||
```
|
||||
|
||||
## Performance Monitoring Commands
|
||||
|
||||
### 1. top
|
||||
**Purpose**: Display running processes
|
||||
**Usage**: `top [OPTIONS...]`
|
||||
**Integration**: Used for process monitoring
|
||||
|
||||
```bash
|
||||
# Display processes
|
||||
top
|
||||
|
||||
# Display specific process
|
||||
top -p $(pgrep bootc)
|
||||
```
|
||||
|
||||
### 2. ps
|
||||
**Purpose**: Display process information
|
||||
**Usage**: `ps [OPTIONS...]`
|
||||
**Integration**: Used for process analysis
|
||||
|
||||
```bash
|
||||
# Display all processes
|
||||
ps aux
|
||||
|
||||
# Display specific process
|
||||
ps aux | grep bootc
|
||||
|
||||
# Display process tree
|
||||
ps auxf
|
||||
```
|
||||
|
||||
### 3. vmstat
|
||||
**Purpose**: Display virtual memory statistics
|
||||
**Usage**: `vmstat [OPTIONS...]`
|
||||
**Integration**: Used for system performance monitoring
|
||||
|
||||
```bash
|
||||
# Display statistics
|
||||
vmstat
|
||||
|
||||
# Display with interval
|
||||
vmstat 1
|
||||
|
||||
# Display specific count
|
||||
vmstat 5 10
|
||||
```
|
||||
|
||||
This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc upgrade system.
|
||||
328
upgrade/quick-reference.md
Normal file
328
upgrade/quick-reference.md
Normal file
|
|
@ -0,0 +1,328 @@
|
|||
# bootc upgrade - Quick Reference
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc upgrade [OPTIONS...]
|
||||
```
|
||||
|
||||
## Common Options
|
||||
|
||||
| Option | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `--check` | Check for updates without downloading | `bootc upgrade --check` |
|
||||
| `--apply` | Apply updates and reboot | `bootc upgrade --apply` |
|
||||
| `--quiet` | Suppress progress output | `bootc upgrade --quiet` |
|
||||
| `--soft-reboot` | Configure soft reboot behavior | `bootc upgrade --apply --soft-reboot=auto` |
|
||||
|
||||
## Soft Reboot Modes
|
||||
|
||||
| Mode | Description | Use Case |
|
||||
|------|-------------|----------|
|
||||
| `required` | Fail if soft reboot unavailable | Virtualized environments |
|
||||
| `auto` | Use soft reboot if available | General use (recommended) |
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Check for Updates
|
||||
|
||||
```bash
|
||||
# Check if updates are available
|
||||
bootc upgrade --check
|
||||
|
||||
# Check quietly
|
||||
bootc upgrade --check --quiet
|
||||
```
|
||||
|
||||
### Download Updates
|
||||
|
||||
```bash
|
||||
# Download and stage updates
|
||||
bootc upgrade
|
||||
|
||||
# Download quietly
|
||||
bootc upgrade --quiet
|
||||
```
|
||||
|
||||
### Apply Updates
|
||||
|
||||
```bash
|
||||
# Apply updates and reboot
|
||||
bootc upgrade --apply
|
||||
|
||||
# Apply with soft reboot
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
|
||||
# Apply with required soft reboot
|
||||
bootc upgrade --apply --soft-reboot=required
|
||||
```
|
||||
|
||||
## Update Workflow
|
||||
|
||||
### 1. Check Phase
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
```
|
||||
|
||||
### 2. Download Phase
|
||||
|
||||
```bash
|
||||
# Download updates
|
||||
bootc upgrade
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
# Staging update...
|
||||
# Update staged successfully
|
||||
```
|
||||
|
||||
### 3. Apply Phase
|
||||
|
||||
```bash
|
||||
# Apply updates
|
||||
bootc upgrade --apply
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
# Staging update...
|
||||
# Update staged successfully
|
||||
# Rebooting system...
|
||||
```
|
||||
|
||||
## Status Commands
|
||||
|
||||
### Check System Status
|
||||
|
||||
```bash
|
||||
# View current status
|
||||
bootc status
|
||||
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# View status in JSON
|
||||
bootc status --json
|
||||
```
|
||||
|
||||
### Status Indicators
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `booted` | Currently running system |
|
||||
| `staged` | Update ready for next boot |
|
||||
| `incompatible` | System has local modifications |
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Manual Updates
|
||||
|
||||
```bash
|
||||
# Check and apply updates
|
||||
bootc upgrade --check
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### 2. Automated Updates
|
||||
|
||||
```bash
|
||||
# Automated update with soft reboot
|
||||
bootc upgrade --apply --soft-reboot=auto --quiet
|
||||
```
|
||||
|
||||
### 3. CI/CD Integration
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# Apply if available
|
||||
if [ $? -eq 0 ]; then
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
fi
|
||||
```
|
||||
|
||||
### 4. Monitoring
|
||||
|
||||
```bash
|
||||
# Check update availability
|
||||
bootc upgrade --check
|
||||
|
||||
# Check system status
|
||||
bootc status
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| No updates available | Check image source with `bootc edit` |
|
||||
| Update fails to download | Check network and authentication |
|
||||
| Update fails to apply | Check system compatibility and logs |
|
||||
| Soft reboot fails | Use `--soft-reboot=auto` or regular reboot |
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc upgrade --check
|
||||
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Check image source
|
||||
bootc edit
|
||||
```
|
||||
|
||||
### Recovery Commands
|
||||
|
||||
```bash
|
||||
# Rollback to previous version
|
||||
bootc rollback
|
||||
|
||||
# Check rollback status
|
||||
bootc status
|
||||
|
||||
# Reset local modifications
|
||||
rpm-ostree reset
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Update Strategy
|
||||
|
||||
- **Test First**: Test updates in staging environment
|
||||
- **Check Before Apply**: Use `--check` before `--apply`
|
||||
- **Use Soft Reboot**: Use `--soft-reboot=auto` when possible
|
||||
- **Monitor Status**: Check `bootc status` regularly
|
||||
|
||||
### 2. Automation
|
||||
|
||||
- **Use `--check`**: For monitoring and CI/CD
|
||||
- **Use `--apply`**: For automated deployments
|
||||
- **Use `--quiet`**: For automated scripts
|
||||
- **Handle Errors**: Check return codes and handle failures
|
||||
|
||||
### 3. Security
|
||||
|
||||
- **Verify Images**: Ensure images are signed and trusted
|
||||
- **Use HTTPS**: Use secure registry connections
|
||||
- **Monitor Logs**: Check system logs for issues
|
||||
- **Test Rollback**: Ensure rollback works before applying
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Systemd Service
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/bootc-update.service
|
||||
[Unit]
|
||||
Description=Update bootc system
|
||||
After=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/bin/update-system.sh
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Cron Job
|
||||
|
||||
```bash
|
||||
# Add to crontab
|
||||
0 2 * * * /usr/local/bin/update-system.sh
|
||||
```
|
||||
|
||||
### Shell Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# update-system.sh
|
||||
|
||||
if bootc upgrade --check; then
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
fi
|
||||
```
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### 1. Speed Optimization
|
||||
|
||||
- **Use `--check`**: For quick availability checks
|
||||
- **Use `--soft-reboot`**: For faster restarts
|
||||
- **Use `--quiet`**: For automated scripts
|
||||
- **Check First**: Use `--check` before downloading
|
||||
|
||||
### 2. Bandwidth Optimization
|
||||
|
||||
- **Check First**: Use `--check` before downloading
|
||||
- **Use Local Mirrors**: Use local registry mirrors
|
||||
- **Incremental Updates**: Only download changed layers
|
||||
- **Offline Updates**: Download updates offline
|
||||
|
||||
### 3. System Impact
|
||||
|
||||
- **Staged Updates**: No impact on running system
|
||||
- **Atomic Application**: All-or-nothing updates
|
||||
- **Rollback Capability**: Quick recovery from issues
|
||||
- **State Preservation**: Preserves `/etc` and `/var`
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Image Security
|
||||
|
||||
- **Signature Verification**: Ensure images are signed
|
||||
- **Registry Security**: Use trusted registries
|
||||
- **Digest Verification**: Verify image digests
|
||||
- **Access Control**: Control update permissions
|
||||
|
||||
### 2. Update Security
|
||||
|
||||
- **Network Security**: Use secure connections
|
||||
- **Authentication**: Authenticate with registries
|
||||
- **Authorization**: Control update permissions
|
||||
- **Audit Logging**: Log all update activities
|
||||
|
||||
### 3. Rollback Security
|
||||
|
||||
- **State Preservation**: Ensure `/etc` and `/var` are secure
|
||||
- **Access Control**: Limit rollback permissions
|
||||
- **Audit Logging**: Log all rollback activities
|
||||
- **Testing**: Test rollback procedures regularly
|
||||
|
||||
## Future Features
|
||||
|
||||
### 1. Planned Enhancements
|
||||
|
||||
- **Userspace Restart**: For kernel-unchanged updates
|
||||
- **Delta Updates**: More efficient layer downloads
|
||||
- **Rollback Automation**: Automatic rollback on failure
|
||||
- **Update Scheduling**: Time-based update application
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for update management
|
||||
- **Webhook Integration**: Event notifications
|
||||
- **Metrics Collection**: Update performance metrics
|
||||
- **Dashboard Integration**: Web-based management
|
||||
|
||||
---
|
||||
|
||||
This quick reference provides essential commands and patterns for using `bootc upgrade` effectively.
|
||||
422
upgrade/technical-reference.md
Normal file
422
upgrade/technical-reference.md
Normal file
|
|
@ -0,0 +1,422 @@
|
|||
# bootc upgrade - Technical Reference
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The bootc upgrade system is built on OSTree's A/B deployment model, providing transactional updates with rollback capabilities. The system integrates with container registries to pull updates and stages them for application at the next boot.
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Upgrade Command Structure
|
||||
|
||||
```rust
|
||||
// From cli.rs:64-89
|
||||
pub(crate) struct UpgradeOpts {
|
||||
pub(crate) quiet: bool, // Suppress progress output
|
||||
pub(crate) check: bool, // Check-only mode
|
||||
pub(crate) apply: bool, // Apply and reboot
|
||||
pub(crate) soft_reboot: Option<SoftRebootMode>, // Soft reboot behavior
|
||||
pub(crate) progress: ProgressOptions, // Progress reporting
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Command-line interface configuration
|
||||
**Features**: Mutually exclusive options, progress control, soft reboot support
|
||||
|
||||
### 2. Upgrade Implementation
|
||||
|
||||
```rust
|
||||
// From cli.rs:860-969
|
||||
async fn upgrade(opts: UpgradeOpts) -> Result<()> {
|
||||
let sysroot = &get_storage().await?;
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = &ostree.repo();
|
||||
let (booted_deployment, _deployments, host) = crate::status::get_status_require_booted(ostree)?;
|
||||
let imgref = host.spec.image.as_ref();
|
||||
let prog: ProgressWriter = opts.progress.try_into()?;
|
||||
// ... upgrade logic
|
||||
}
|
||||
```
|
||||
|
||||
**Process Flow**:
|
||||
1. **System Validation**: Check system status and compatibility
|
||||
2. **Image Resolution**: Determine source image reference
|
||||
3. **Update Check**: Verify if updates are available
|
||||
4. **Download/Stage**: Pull and stage updates
|
||||
5. **Application**: Apply updates if requested
|
||||
|
||||
## Upgrade Modes
|
||||
|
||||
### 1. Check Mode (`--check`)
|
||||
|
||||
```rust
|
||||
// From cli.rs:894-915
|
||||
if opts.check {
|
||||
let imgref = imgref.clone().into();
|
||||
let mut imp = crate::deploy::new_importer(repo, &imgref).await?;
|
||||
match imp.prepare().await? {
|
||||
PrepareResult::AlreadyPresent(_) => {
|
||||
println!("No changes in: {imgref:#}");
|
||||
}
|
||||
PrepareResult::Ready(r) => {
|
||||
crate::deploy::check_bootc_label(&r.config);
|
||||
println!("Update available for: {imgref:#}");
|
||||
if let Some(version) = r.version() {
|
||||
println!(" Version: {version}");
|
||||
}
|
||||
println!(" Digest: {}", r.manifest_digest);
|
||||
changed = true;
|
||||
// ... diff printing
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Check for updates without downloading
|
||||
**Benefits**: Fast execution, minimal bandwidth usage
|
||||
**Output**: Update availability, version info, digest comparison
|
||||
|
||||
### 2. Download Mode (default)
|
||||
|
||||
```rust
|
||||
// From cli.rs:916-949
|
||||
let fetched = crate::deploy::pull(repo, imgref, None, opts.quiet, prog.clone()).await?;
|
||||
let staged_digest = staged_image.map(|s| s.digest().expect("valid digest in status"));
|
||||
let fetched_digest = &fetched.manifest_digest;
|
||||
|
||||
let staged_unchanged = staged_digest
|
||||
.as_ref()
|
||||
.map(|d| d == fetched_digest)
|
||||
.unwrap_or_default();
|
||||
let booted_unchanged = booted_image
|
||||
.as_ref()
|
||||
.map(|img| &img.manifest_digest == fetched_digest)
|
||||
.unwrap_or_default();
|
||||
|
||||
if staged_unchanged {
|
||||
println!("Staged update present, not changed.");
|
||||
handle_staged_soft_reboot(ostree, opts.soft_reboot, &host)?;
|
||||
if opts.apply {
|
||||
crate::reboot::reboot()?;
|
||||
}
|
||||
} else if booted_unchanged {
|
||||
println!("No update available.")
|
||||
} else {
|
||||
let osname = booted_deployment.osname();
|
||||
crate::deploy::stage(sysroot, &osname, &fetched, &spec, prog.clone()).await?;
|
||||
changed = true;
|
||||
// ... diff printing
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Download and stage updates
|
||||
**Process**: Registry pull → OSTree import → Staging → Status update
|
||||
**Features**: Duplicate detection, progress reporting, diff display
|
||||
|
||||
### 3. Apply Mode (`--apply`)
|
||||
|
||||
```rust
|
||||
// From cli.rs:951-968
|
||||
if changed {
|
||||
sysroot.update_mtime()?;
|
||||
|
||||
if opts.soft_reboot.is_some() {
|
||||
let updated_host = crate::status::get_status(ostree, Some(&booted_deployment))?.1;
|
||||
handle_staged_soft_reboot(ostree, opts.soft_reboot, &updated_host)?;
|
||||
}
|
||||
|
||||
if opts.apply {
|
||||
crate::reboot::reboot()?;
|
||||
}
|
||||
} else {
|
||||
tracing::debug!("No changes");
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Apply staged updates and reboot
|
||||
**Process**: Update system status → Handle soft reboot → Reboot system
|
||||
**Features**: Soft reboot support, automatic reboot, status updates
|
||||
|
||||
## Soft Reboot System
|
||||
|
||||
### 1. Soft Reboot Modes
|
||||
|
||||
```rust
|
||||
// From cli.rs:81-85
|
||||
#[clap(long = "soft-reboot", conflicts_with = "check")]
|
||||
pub(crate) soft_reboot: Option<SoftRebootMode>,
|
||||
```
|
||||
|
||||
**Modes**:
|
||||
- `required`: Fail if soft reboot unavailable
|
||||
- `auto`: Use soft reboot if available, fallback to regular reboot
|
||||
|
||||
### 2. Soft Reboot Handling
|
||||
|
||||
```rust
|
||||
// From cli.rs:954-959
|
||||
if opts.soft_reboot.is_some() {
|
||||
let updated_host = crate::status::get_status(ostree, Some(&booted_deployment))?.1;
|
||||
handle_staged_soft_reboot(ostree, opts.soft_reboot, &updated_host)?;
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Configure soft reboot behavior
|
||||
**Process**: Check availability → Configure if supported → Fallback if needed
|
||||
|
||||
## Registry Integration
|
||||
|
||||
### 1. Image Reference Resolution
|
||||
|
||||
```rust
|
||||
// From cli.rs:865-889
|
||||
let imgref = host.spec.image.as_ref();
|
||||
let booted_image = host
|
||||
.status
|
||||
.booted
|
||||
.as_ref()
|
||||
.map(|b| b.query_image(repo))
|
||||
.transpose()?
|
||||
.flatten();
|
||||
let imgref = imgref.ok_or_else(|| anyhow::anyhow!("No image source specified"))?;
|
||||
```
|
||||
|
||||
**Purpose**: Determine source image for updates
|
||||
**Process**: Get from host spec → Validate availability → Use for upgrade
|
||||
|
||||
### 2. Container Registry Pull
|
||||
|
||||
```rust
|
||||
// From cli.rs:917
|
||||
let fetched = crate::deploy::pull(repo, imgref, None, opts.quiet, prog.clone()).await?;
|
||||
```
|
||||
|
||||
**Purpose**: Download container image from registry
|
||||
**Process**: Registry authentication → Layer download → OSTree conversion
|
||||
**Features**: Progress reporting, error handling, signature verification
|
||||
|
||||
## OSTree Integration
|
||||
|
||||
### 1. Deployment Management
|
||||
|
||||
```rust
|
||||
// From cli.rs:864
|
||||
let (booted_deployment, _deployments, host) = crate::status::get_status_require_booted(ostree)?;
|
||||
```
|
||||
|
||||
**Purpose**: Get current system state
|
||||
**Process**: Query OSTree → Get booted deployment → Get host configuration
|
||||
|
||||
### 2. Staging Process
|
||||
|
||||
```rust
|
||||
// From cli.rs:940
|
||||
crate::deploy::stage(sysroot, &osname, &fetched, &spec, prog.clone()).await?;
|
||||
```
|
||||
|
||||
**Purpose**: Stage updates for next boot
|
||||
**Process**: Create new deployment → Configure bootloader → Update status
|
||||
**Features**: Atomic staging, rollback capability, state preservation
|
||||
|
||||
## Status Management
|
||||
|
||||
### 1. System Status Query
|
||||
|
||||
```rust
|
||||
// From cli.rs:864
|
||||
let (booted_deployment, _deployments, host) = crate::status::get_status_require_booted(ostree)?;
|
||||
```
|
||||
|
||||
**Purpose**: Get current system state
|
||||
**Returns**: Booted deployment, all deployments, host configuration
|
||||
|
||||
### 2. Status Updates
|
||||
|
||||
```rust
|
||||
// From cli.rs:952
|
||||
sysroot.update_mtime()?;
|
||||
```
|
||||
|
||||
**Purpose**: Update system modification time
|
||||
**Process**: Update filesystem timestamp → Trigger status refresh
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Compatibility Checks
|
||||
|
||||
```rust
|
||||
// From cli.rs:869-879
|
||||
if imgref.is_none() {
|
||||
let booted_incompatible = host.status.booted.as_ref().is_some_and(|b| b.incompatible);
|
||||
let staged_incompatible = host.status.staged.as_ref().is_some_and(|b| b.incompatible);
|
||||
|
||||
if booted_incompatible || staged_incompatible {
|
||||
return Err(anyhow::anyhow!(
|
||||
"Deployment contains local rpm-ostree modifications; cannot upgrade via bootc. You can run `rpm-ostree reset` to undo the modifications."
|
||||
));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Check system compatibility
|
||||
**Checks**: Local modifications, incompatible deployments
|
||||
**Error**: Prevents upgrade on incompatible systems
|
||||
|
||||
### 2. Update Validation
|
||||
|
||||
```rust
|
||||
// From cli.rs:902
|
||||
crate::deploy::check_bootc_label(&r.config);
|
||||
```
|
||||
|
||||
**Purpose**: Validate container image compatibility
|
||||
**Checks**: bootc labels, image configuration
|
||||
**Error**: Prevents upgrade of incompatible images
|
||||
|
||||
## Progress Reporting
|
||||
|
||||
### 1. Progress Writer
|
||||
|
||||
```rust
|
||||
// From cli.rs:866
|
||||
let prog: ProgressWriter = opts.progress.try_into()?;
|
||||
```
|
||||
|
||||
**Purpose**: Handle progress output
|
||||
**Features**: Quiet mode support, progress bars, status updates
|
||||
|
||||
### 2. Progress Options
|
||||
|
||||
```rust
|
||||
// From cli.rs:87-88
|
||||
#[clap(flatten)]
|
||||
pub(crate) progress: ProgressOptions,
|
||||
```
|
||||
|
||||
**Purpose**: Configure progress display
|
||||
**Options**: Quiet mode, progress bars, status updates
|
||||
|
||||
## Diff and Comparison
|
||||
|
||||
### 1. Manifest Comparison
|
||||
|
||||
```rust
|
||||
// From cli.rs:910-913
|
||||
if let Some(previous_image) = booted_image.as_ref() {
|
||||
let diff = ostree_container::ManifestDiff::new(&previous_image.manifest, &r.manifest);
|
||||
diff.print();
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Show differences between images
|
||||
**Process**: Compare manifests → Generate diff → Display changes
|
||||
**Features**: Layer changes, configuration differences, size changes
|
||||
|
||||
### 2. Update Information
|
||||
|
||||
```rust
|
||||
// From cli.rs:903-908
|
||||
println!("Update available for: {imgref:#}");
|
||||
if let Some(version) = r.version() {
|
||||
println!(" Version: {version}");
|
||||
}
|
||||
println!(" Digest: {}", r.manifest_digest);
|
||||
```
|
||||
|
||||
**Purpose**: Display update information
|
||||
**Information**: Image reference, version, digest, changes
|
||||
|
||||
## System Integration
|
||||
|
||||
### 1. Storage Management
|
||||
|
||||
```rust
|
||||
// From cli.rs:861
|
||||
let sysroot = &get_storage().await?;
|
||||
```
|
||||
|
||||
**Purpose**: Get system storage interface
|
||||
**Features**: OSTree integration, filesystem management
|
||||
|
||||
### 2. Reboot Integration
|
||||
|
||||
```rust
|
||||
// From cli.rs:962
|
||||
crate::reboot::reboot()?;
|
||||
```
|
||||
|
||||
**Purpose**: Reboot system after update
|
||||
**Process**: Trigger system reboot → Apply staged updates
|
||||
**Features**: Soft reboot support, reboot coordination
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
### 1. Duplicate Detection
|
||||
|
||||
```rust
|
||||
// From cli.rs:922-929
|
||||
let staged_unchanged = staged_digest
|
||||
.as_ref()
|
||||
.map(|d| d == fetched_digest)
|
||||
.unwrap_or_default();
|
||||
let booted_unchanged = booted_image
|
||||
.as_ref()
|
||||
.map(|img| &img.manifest_digest == fetched_digest)
|
||||
.unwrap_or_default();
|
||||
```
|
||||
|
||||
**Purpose**: Avoid unnecessary downloads
|
||||
**Process**: Compare digests → Skip if unchanged
|
||||
**Benefits**: Reduced bandwidth, faster execution
|
||||
|
||||
### 2. Incremental Updates
|
||||
|
||||
```rust
|
||||
// From cli.rs:917
|
||||
let fetched = crate::deploy::pull(repo, imgref, None, opts.quiet, prog.clone()).await?;
|
||||
```
|
||||
|
||||
**Purpose**: Download only changed layers
|
||||
**Process**: Registry comparison → Layer download → OSTree import
|
||||
**Benefits**: Reduced bandwidth, faster updates
|
||||
|
||||
## Security Features
|
||||
|
||||
### 1. Signature Verification
|
||||
|
||||
```rust
|
||||
// From cli.rs:917
|
||||
let fetched = crate::deploy::pull(repo, imgref, None, opts.quiet, prog.clone()).await?;
|
||||
```
|
||||
|
||||
**Purpose**: Verify image signatures
|
||||
**Process**: Registry authentication → Signature verification → Image validation
|
||||
**Features**: Cryptographic verification, trust validation
|
||||
|
||||
### 2. Image Validation
|
||||
|
||||
```rust
|
||||
// From cli.rs:902
|
||||
crate::deploy::check_bootc_label(&r.config);
|
||||
```
|
||||
|
||||
**Purpose**: Validate image compatibility
|
||||
**Process**: Check bootc labels → Verify configuration → Validate compatibility
|
||||
**Features**: Label verification, configuration validation
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Userspace Restart**: For kernel-unchanged updates
|
||||
- **Delta Updates**: More efficient layer downloads
|
||||
- **Rollback Automation**: Automatic rollback on failure
|
||||
- **Update Scheduling**: Time-based update application
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for update management
|
||||
- **Webhook Integration**: Event notifications
|
||||
- **Metrics Collection**: Update performance metrics
|
||||
- **Dashboard Integration**: Web-based management
|
||||
|
||||
This technical reference provides comprehensive understanding of the bootc upgrade system's architecture, implementation, and integration patterns.
|
||||
870
usr-overlay/bootc-usr-overlay-external-commands.md
Normal file
870
usr-overlay/bootc-usr-overlay-external-commands.md
Normal file
|
|
@ -0,0 +1,870 @@
|
|||
# bootc usr-overlay - 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 usr-overlay` system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc usr-overlay into larger systems.
|
||||
|
||||
## Core System Commands
|
||||
|
||||
### 1. bootc Commands
|
||||
|
||||
#### bootc usr-overlay
|
||||
**Purpose**: Add transient writable overlayfs on /usr
|
||||
**Usage**: `bootc usr-overlay [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment unlocking
|
||||
- `mount` - For overlay filesystem operations
|
||||
- `umount` - For overlay unmounting
|
||||
|
||||
```bash
|
||||
# Add transient writable overlay on /usr
|
||||
bootc usr-overlay
|
||||
|
||||
# Alternative command name
|
||||
bootc usroverlay
|
||||
```
|
||||
|
||||
#### bootc status
|
||||
**Purpose**: Check system status and deployment information
|
||||
**Usage**: `bootc status [OPTIONS...]`
|
||||
**Integration**: Used to check system state before/after overlay
|
||||
|
||||
```bash
|
||||
# Check system status before overlay
|
||||
bootc status
|
||||
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Check system status after overlay
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 2. OSTree Commands
|
||||
|
||||
#### ostree admin unlock
|
||||
**Purpose**: Unlock OSTree deployment for modifications
|
||||
**Usage**: `ostree admin unlock [OPTIONS...]`
|
||||
**Integration**: Core command used by bootc usr-overlay
|
||||
|
||||
```bash
|
||||
# Unlock current deployment
|
||||
ostree admin unlock
|
||||
|
||||
# Unlock with verbose output
|
||||
ostree admin unlock --verbose
|
||||
|
||||
# Check unlock status
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
#### ostree admin status
|
||||
**Purpose**: Check OSTree deployment status
|
||||
**Usage**: `ostree admin status [OPTIONS...]`
|
||||
**Integration**: Used to verify deployment state
|
||||
|
||||
```bash
|
||||
# Check deployment status
|
||||
ostree admin status
|
||||
|
||||
# Check specific deployment
|
||||
ostree admin status --deployment=deployment-id
|
||||
|
||||
# Check with verbose output
|
||||
ostree admin status --verbose
|
||||
```
|
||||
|
||||
#### ostree admin lock
|
||||
**Purpose**: Lock OSTree deployment
|
||||
**Usage**: `ostree admin lock [OPTIONS...]`
|
||||
**Integration**: Used to restore read-only state
|
||||
|
||||
```bash
|
||||
# Lock current deployment
|
||||
ostree admin lock
|
||||
|
||||
# Lock with verbose output
|
||||
ostree admin lock --verbose
|
||||
```
|
||||
|
||||
### 3. Filesystem Commands
|
||||
|
||||
#### mount
|
||||
**Purpose**: Mount filesystems
|
||||
**Usage**: `mount [OPTIONS...] [DEVICE] [DIRECTORY]`
|
||||
**Integration**: Used for overlay filesystem operations
|
||||
|
||||
```bash
|
||||
# List all mounts
|
||||
mount
|
||||
|
||||
# List mounts for specific directory
|
||||
mount | grep /usr
|
||||
|
||||
# Mount overlay filesystem
|
||||
mount -t overlay overlay -o lowerdir=/usr,upperdir=/tmp/upper,workdir=/tmp/work /usr
|
||||
```
|
||||
|
||||
#### umount
|
||||
**Purpose**: Unmount filesystems
|
||||
**Usage**: `umount [OPTIONS...] [DIRECTORY]`
|
||||
**Integration**: Used for unmounting overlay
|
||||
|
||||
```bash
|
||||
# Unmount /usr
|
||||
umount /usr
|
||||
|
||||
# Lazy unmount /usr
|
||||
umount -l /usr
|
||||
|
||||
# Force unmount /usr
|
||||
umount -f /usr
|
||||
```
|
||||
|
||||
#### mountpoint
|
||||
**Purpose**: Check if directory is mount point
|
||||
**Usage**: `mountpoint [OPTIONS...] [DIRECTORY]`
|
||||
**Integration**: Used to verify mount status
|
||||
|
||||
```bash
|
||||
# Check if /usr is mount point
|
||||
mountpoint /usr
|
||||
|
||||
# Check with verbose output
|
||||
mountpoint -v /usr
|
||||
```
|
||||
|
||||
## Package Manager Commands
|
||||
|
||||
### 1. APT Commands (Debian/Ubuntu)
|
||||
|
||||
#### apt
|
||||
**Purpose**: Advanced Package Tool
|
||||
**Usage**: `apt [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Used for package installation in overlay
|
||||
|
||||
```bash
|
||||
# Update package lists
|
||||
apt update
|
||||
|
||||
# Install packages
|
||||
apt install -y package-name
|
||||
|
||||
# Install multiple packages
|
||||
apt install -y strace gdb valgrind
|
||||
|
||||
# Search packages
|
||||
apt search package-name
|
||||
|
||||
# Show package information
|
||||
apt show package-name
|
||||
```
|
||||
|
||||
#### apt-get
|
||||
**Purpose**: APT package handling utility
|
||||
**Usage**: `apt-get [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Alternative to apt command
|
||||
|
||||
```bash
|
||||
# Update package lists
|
||||
apt-get update
|
||||
|
||||
# Install packages
|
||||
apt-get install -y package-name
|
||||
|
||||
# Remove packages
|
||||
apt-get remove package-name
|
||||
|
||||
# Clean package cache
|
||||
apt-get clean
|
||||
```
|
||||
|
||||
#### dpkg
|
||||
**Purpose**: Debian package manager
|
||||
**Usage**: `dpkg [OPTIONS...] [PACKAGE...]`
|
||||
**Integration**: Low-level package operations
|
||||
|
||||
```bash
|
||||
# Install package
|
||||
dpkg -i package.deb
|
||||
|
||||
# List installed packages
|
||||
dpkg -l
|
||||
|
||||
# Show package information
|
||||
dpkg -s package-name
|
||||
|
||||
# Check package status
|
||||
dpkg -l | grep package-name
|
||||
```
|
||||
|
||||
### 2. DNF Commands (Fedora/RHEL)
|
||||
|
||||
#### dnf
|
||||
**Purpose**: Dandified YUM
|
||||
**Usage**: `dnf [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Used for package installation in overlay
|
||||
|
||||
```bash
|
||||
# Update package lists
|
||||
dnf check-update
|
||||
|
||||
# Install packages
|
||||
dnf install -y package-name
|
||||
|
||||
# Install multiple packages
|
||||
dnf install -y strace gdb valgrind
|
||||
|
||||
# Search packages
|
||||
dnf search package-name
|
||||
|
||||
# Show package information
|
||||
dnf info package-name
|
||||
```
|
||||
|
||||
#### yum
|
||||
**Purpose**: Yellowdog Updater Modified
|
||||
**Usage**: `yum [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Alternative to dnf command
|
||||
|
||||
```bash
|
||||
# Update package lists
|
||||
yum check-update
|
||||
|
||||
# Install packages
|
||||
yum install -y package-name
|
||||
|
||||
# Remove packages
|
||||
yum remove package-name
|
||||
|
||||
# Clean package cache
|
||||
yum clean all
|
||||
```
|
||||
|
||||
#### rpm
|
||||
**Purpose**: RPM Package Manager
|
||||
**Usage**: `rpm [OPTIONS...] [PACKAGE...]`
|
||||
**Integration**: Low-level package operations
|
||||
|
||||
```bash
|
||||
# Install package
|
||||
rpm -i package.rpm
|
||||
|
||||
# List installed packages
|
||||
rpm -qa
|
||||
|
||||
# Show package information
|
||||
rpm -qi package-name
|
||||
|
||||
# Check package status
|
||||
rpm -q package-name
|
||||
```
|
||||
|
||||
## System Monitoring Commands
|
||||
|
||||
### 1. Process Monitoring
|
||||
|
||||
#### lsof
|
||||
**Purpose**: List open files
|
||||
**Usage**: `lsof [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used to check processes using /usr
|
||||
|
||||
```bash
|
||||
# List processes using /usr
|
||||
lsof /usr
|
||||
|
||||
# List processes using specific file
|
||||
lsof /usr/bin/package
|
||||
|
||||
# List all open files
|
||||
lsof
|
||||
|
||||
# List files for specific process
|
||||
lsof -p PID
|
||||
```
|
||||
|
||||
#### ps
|
||||
**Purpose**: Display running processes
|
||||
**Usage**: `ps [OPTIONS...]`
|
||||
**Integration**: Used for process monitoring
|
||||
|
||||
```bash
|
||||
# Display all processes
|
||||
ps aux
|
||||
|
||||
# Display processes using /usr
|
||||
ps aux | grep /usr
|
||||
|
||||
# Display process tree
|
||||
ps auxf
|
||||
```
|
||||
|
||||
#### pgrep
|
||||
**Purpose**: Find processes by name
|
||||
**Usage**: `pgrep [OPTIONS...] PATTERN`
|
||||
**Integration**: Used for process identification
|
||||
|
||||
```bash
|
||||
# Find processes by name
|
||||
pgrep package-name
|
||||
|
||||
# Find processes with full command line
|
||||
pgrep -f package-name
|
||||
|
||||
# Find processes using /usr
|
||||
pgrep -f /usr
|
||||
```
|
||||
|
||||
### 2. Filesystem Monitoring
|
||||
|
||||
#### df
|
||||
**Purpose**: Display filesystem disk space usage
|
||||
**Usage**: `df [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for disk space monitoring
|
||||
|
||||
```bash
|
||||
# Check disk usage
|
||||
df -h
|
||||
|
||||
# Check /usr usage
|
||||
df -h /usr
|
||||
|
||||
# Check inode usage
|
||||
df -i /usr
|
||||
```
|
||||
|
||||
#### du
|
||||
**Purpose**: Display directory space usage
|
||||
**Usage**: `du [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for directory space analysis
|
||||
|
||||
```bash
|
||||
# Check /usr usage
|
||||
du -sh /usr
|
||||
|
||||
# Check overlay usage
|
||||
du -sh /tmp/upper
|
||||
|
||||
# Check work directory usage
|
||||
du -sh /tmp/work
|
||||
```
|
||||
|
||||
#### find
|
||||
**Purpose**: Search for files
|
||||
**Usage**: `find [PATH...] [EXPRESSION...]`
|
||||
**Integration**: Used for finding files in overlay
|
||||
|
||||
```bash
|
||||
# Find files in /usr
|
||||
find /usr -name "package-name"
|
||||
|
||||
# Find recently modified files
|
||||
find /usr -mtime -1
|
||||
|
||||
# Find files by size
|
||||
find /usr -size +100M
|
||||
```
|
||||
|
||||
## System Information Commands
|
||||
|
||||
### 1. System Status
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
### 2. Hardware Information
|
||||
|
||||
#### lscpu
|
||||
**Purpose**: Display CPU information
|
||||
**Usage**: `lscpu [OPTIONS...]`
|
||||
**Integration**: Used for system resource analysis
|
||||
|
||||
```bash
|
||||
# Display CPU information
|
||||
lscpu
|
||||
|
||||
# Display in specific format
|
||||
lscpu --extended
|
||||
```
|
||||
|
||||
#### lsblk
|
||||
**Purpose**: List block devices
|
||||
**Usage**: `lsblk [OPTIONS...]`
|
||||
**Integration**: Used for storage device identification
|
||||
|
||||
```bash
|
||||
# List all block devices
|
||||
lsblk
|
||||
|
||||
# List with filesystem information
|
||||
lsblk -f
|
||||
|
||||
# List specific device
|
||||
lsblk /dev/sda
|
||||
```
|
||||
|
||||
## 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 /etc/bootc/config.yaml
|
||||
|
||||
# Display first bytes
|
||||
head -c 100 /etc/bootc/config.yaml
|
||||
```
|
||||
|
||||
## Network Commands
|
||||
|
||||
### 1. HTTP Clients
|
||||
|
||||
#### curl
|
||||
**Purpose**: HTTP client for registry communication
|
||||
**Usage**: `curl [OPTIONS...] URL`
|
||||
**Integration**: Used for registry API calls and authentication
|
||||
|
||||
```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/v2.0
|
||||
|
||||
# Authenticate with registry
|
||||
curl -u username:password https://quay.io/v2/token
|
||||
```
|
||||
|
||||
#### 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/v2.0
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
## 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 /etc/bootc/config.yaml
|
||||
|
||||
# Display with line numbers
|
||||
cat -n /etc/bootc/config.yaml
|
||||
|
||||
# Display non-printing characters
|
||||
cat -v /etc/bootc/config.yaml
|
||||
```
|
||||
|
||||
#### cp
|
||||
**Purpose**: Copy files
|
||||
**Usage**: `cp [OPTIONS...] SOURCE DEST`
|
||||
**Integration**: Used for backing up configuration files
|
||||
|
||||
```bash
|
||||
# Copy file
|
||||
cp /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
|
||||
|
||||
# Copy with preserve attributes
|
||||
cp -p /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
|
||||
|
||||
# Copy recursively
|
||||
cp -r /etc/bootc/ /etc/bootc.backup/
|
||||
```
|
||||
|
||||
#### mv
|
||||
**Purpose**: Move or rename files
|
||||
**Usage**: `mv [OPTIONS...] SOURCE DEST`
|
||||
**Integration**: Used for renaming configuration files
|
||||
|
||||
```bash
|
||||
# Rename file
|
||||
mv /etc/bootc/config.yaml /etc/bootc/config.yaml.old
|
||||
|
||||
# Move file
|
||||
mv /etc/bootc/config.yaml /backup/config.yaml
|
||||
```
|
||||
|
||||
#### rm
|
||||
**Purpose**: Remove files
|
||||
**Usage**: `rm [OPTIONS...] FILE...`
|
||||
**Integration**: Used for cleaning up temporary files
|
||||
|
||||
```bash
|
||||
# Remove file
|
||||
rm /etc/bootc/config.yaml
|
||||
|
||||
# Remove with confirmation
|
||||
rm -i /etc/bootc/config.yaml
|
||||
|
||||
# Remove recursively
|
||||
rm -r /etc/bootc/
|
||||
```
|
||||
|
||||
### 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/
|
||||
```
|
||||
|
||||
## 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. I/O Monitoring
|
||||
|
||||
#### iostat
|
||||
**Purpose**: Display I/O statistics
|
||||
**Usage**: `iostat [OPTIONS...] [INTERVAL] [COUNT]`
|
||||
**Integration**: Used for I/O performance monitoring
|
||||
|
||||
```bash
|
||||
# Display I/O statistics
|
||||
iostat
|
||||
|
||||
# Display with interval
|
||||
iostat 1 5
|
||||
|
||||
# Display specific devices
|
||||
iostat -x /dev/sda
|
||||
```
|
||||
|
||||
#### iotop
|
||||
**Purpose**: Display I/O usage by process
|
||||
**Usage**: `iotop [OPTIONS...]`
|
||||
**Integration**: Used for I/O process monitoring
|
||||
|
||||
```bash
|
||||
# Display I/O usage
|
||||
iotop
|
||||
|
||||
# Display only processes doing I/O
|
||||
iotop -o
|
||||
|
||||
# Display with batch mode
|
||||
iotop -b
|
||||
```
|
||||
|
||||
## Automation and Scripting Commands
|
||||
|
||||
### 1. Shell Scripting
|
||||
|
||||
#### bash
|
||||
**Purpose**: Bourne Again Shell
|
||||
**Usage**: `bash [OPTIONS...] [FILE]`
|
||||
**Integration**: Used for automation scripts
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Check if overlay is active
|
||||
if mount | grep -q overlay; then
|
||||
echo "Overlay is active"
|
||||
else
|
||||
echo "Overlay is not active"
|
||||
fi
|
||||
```
|
||||
|
||||
#### sh
|
||||
**Purpose**: POSIX shell
|
||||
**Usage**: `sh [OPTIONS...] [FILE]`
|
||||
**Integration**: Used for portable scripts
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
# Check if /usr is writable
|
||||
if touch /usr/test-file 2>/dev/null; then
|
||||
echo "/usr is writable"
|
||||
rm -f /usr/test-file
|
||||
else
|
||||
echo "/usr is read-only"
|
||||
fi
|
||||
```
|
||||
|
||||
### 2. Process Control
|
||||
|
||||
#### pkill
|
||||
**Purpose**: Kill processes by name
|
||||
**Usage**: `pkill [OPTIONS...] PATTERN`
|
||||
**Integration**: Used for process termination
|
||||
|
||||
```bash
|
||||
# Kill processes by name
|
||||
pkill package-name
|
||||
|
||||
# Kill with signal
|
||||
pkill -9 package-name
|
||||
|
||||
# Kill with specific user
|
||||
pkill -u root package-name
|
||||
```
|
||||
|
||||
#### kill
|
||||
**Purpose**: Send signal to process
|
||||
**Usage**: `kill [OPTIONS...] PID`
|
||||
**Integration**: Used for process control
|
||||
|
||||
```bash
|
||||
# Send TERM signal
|
||||
kill 1234
|
||||
|
||||
# Send KILL signal
|
||||
kill -9 1234
|
||||
|
||||
# Send HUP signal
|
||||
kill -HUP 1234
|
||||
```
|
||||
|
||||
## 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 /etc/bootc/config.yaml
|
||||
|
||||
# Commit changes
|
||||
git commit -m "Update configuration"
|
||||
|
||||
# Check status
|
||||
git status
|
||||
```
|
||||
|
||||
This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc usr-overlay system.
|
||||
421
usr-overlay/bootc-usr-overlay-flowchart.md
Normal file
421
usr-overlay/bootc-usr-overlay-flowchart.md
Normal file
|
|
@ -0,0 +1,421 @@
|
|||
# bootc usr-overlay - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc usr-overlay` process flow, showing the decision points, operations, and filesystem changes involved in creating a transient writable overlay on the `/usr` directory.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc usr-overlay │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Validate Prerequisites │
|
||||
│ │
|
||||
│ • Check if running as root or with appropriate privileges │
|
||||
│ • Verify OSTree is available and accessible │
|
||||
│ • Check if system is bootc-compatible │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Current State │
|
||||
│ │
|
||||
│ • Check if /usr is currently read-only │
|
||||
│ • Verify OSTree deployment status │
|
||||
│ • Check if overlay is already active │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute OSTree Unlock │
|
||||
│ │
|
||||
│ • Call `ostree admin unlock` command │
|
||||
│ • Create overlay filesystem on /usr │
|
||||
│ • Make /usr directory writable │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Overlay Creation │
|
||||
│ │
|
||||
│ • Check if overlay filesystem is mounted │
|
||||
│ • Verify /usr is now writable │
|
||||
│ • Confirm overlay structure is correct │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Provide User Feedback │
|
||||
│ │
|
||||
│ • Display success message │
|
||||
│ • Inform user about overlay status │
|
||||
│ • Provide usage instructions │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Transient overlay active on /usr │
|
||||
│ • /usr directory is now writable │
|
||||
│ • Changes will be discarded on reboot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## OSTree Unlock Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ OSTree Admin Unlock │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Deployment Status │
|
||||
│ │
|
||||
│ • Get current OSTree deployment │
|
||||
│ • Check if deployment is locked │
|
||||
│ • Verify deployment is bootable │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Overlay Filesystem │
|
||||
│ │
|
||||
│ • Set up overlay filesystem structure │
|
||||
│ • Create lower layer (original /usr) │
|
||||
│ • Create upper layer (writable overlay) │
|
||||
│ • Create work directory (temporary files) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Mount Overlay on /usr │
|
||||
│ │
|
||||
│ • Mount overlay filesystem on /usr │
|
||||
│ • Set up copy-on-write mechanism │
|
||||
│ • Enable write operations on /usr │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Update OSTree State │
|
||||
│ │
|
||||
│ • Mark deployment as unlocked │
|
||||
│ • Update deployment metadata │
|
||||
│ • Set up auto-lock on reboot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Overlay filesystem active │
|
||||
│ • /usr directory writable │
|
||||
│ • Changes will be transient │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Overlay Filesystem Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Overlay Filesystem Structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ /usr (Mount Point) │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Overlay Mount │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ Lower Layer │ │ Upper Layer │ │ Work Layer │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Original /usr │ │ • Writable │ │ • Temporary │ │ │
|
||||
│ │ │ • Read-only │ │ • Changes │ │ • COW files │ │ │
|
||||
│ │ │ • Base system │ │ • New files │ │ • Metadata │ │ │
|
||||
│ │ │ • Immutable │ │ • Modifications │ │ • Operations│ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Package Installation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Package Installation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Overlay Status │
|
||||
│ │
|
||||
│ • Verify /usr is writable │
|
||||
│ • Check overlay filesystem is active │
|
||||
│ • Confirm package manager can operate │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Package Manager Operation │
|
||||
│ │
|
||||
│ • Update package lists (apt update, dnf check-update) │
|
||||
│ • Download package files │
|
||||
│ • Install packages to overlay │
|
||||
│ • Update package database │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Overlay Write Operations │
|
||||
│ │
|
||||
│ • Files written to upper layer │
|
||||
│ • Copy-on-write for modified files │
|
||||
│ • Metadata updated in overlay │
|
||||
│ • Original files preserved in lower layer │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Installation │
|
||||
│ │
|
||||
│ • Check if packages are accessible │
|
||||
│ │ • Verify files are in overlay │
|
||||
│ │ • Test package functionality │
|
||||
│ │ • Confirm changes are transient │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Unmounting Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Unmounting Overlay │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Active Processes │
|
||||
│ │
|
||||
│ • Identify processes using /usr files │
|
||||
│ • Check for open file handles │
|
||||
│ • Determine if unmount is safe │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Choose Unmount Method │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Can unmount safely? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Regular ││ │ │ Lazy Unmount ││ │
|
||||
│ │ │ Unmount ││ │ │ ││ │
|
||||
│ │ │ • umount ││ │ │ • umount -l /usr ││ │
|
||||
│ │ │ /usr ││ │ │ • Unmount when references ││ │
|
||||
│ │ │ • Immediate ││ │ │ released ││ │
|
||||
│ │ │ unmount ││ │ │ • Safer for active processes ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Clean Up Overlay │
|
||||
│ │
|
||||
│ • Remove overlay filesystem │
|
||||
│ • Clean up work directory │
|
||||
│ • Restore original /usr state │
|
||||
│ • Update OSTree deployment status │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Unmount │
|
||||
│ │
|
||||
│ • Check /usr is no longer writable │
|
||||
│ • Verify overlay is removed │
|
||||
│ • Confirm original state restored │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Overlay successfully removed │
|
||||
│ • /usr returned to read-only state │
|
||||
│ • All changes discarded │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Permission │ │ OSTree │ │ System │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Not root │ │ • OSTree not │ │ • /usr already │ │
|
||||
│ │ • Permission │ │ available │ │ writable │ │
|
||||
│ │ denied │ │ • Deployment │ │ • Overlay │ │
|
||||
│ │ • Insufficient │ │ locked │ │ already │ │
|
||||
│ │ privileges │ │ • Command │ │ active │ │
|
||||
│ │ │ │ failed │ │ • Mount │ │
|
||||
│ │ │ │ │ │ failed │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up any partial state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initial State │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ /usr Read-only State │ │
|
||||
│ │ │ │
|
||||
│ │ • /usr mounted read-only │ │
|
||||
│ │ • OSTree deployment locked │ │
|
||||
│ │ • No overlay filesystem │ │
|
||||
│ │ • Immutable system state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ bootc usr-overlay │ │
|
||||
│ │ │ │
|
||||
│ │ • Call ostree admin unlock │ │
|
||||
│ │ • Create overlay filesystem │ │
|
||||
│ │ • Mount overlay on /usr │ │
|
||||
│ │ • Enable write operations │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ /usr Writable State │ │
|
||||
│ │ │ │
|
||||
│ │ • /usr mounted with overlay │ │
|
||||
│ │ • OSTree deployment unlocked │ │
|
||||
│ │ • Overlay filesystem active │ │
|
||||
│ │ • Writable system state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Package Operations │ │
|
||||
│ │ │ │
|
||||
│ │ • Install packages to overlay │ │
|
||||
│ │ • Modify files in overlay │ │
|
||||
│ │ • Use installed tools │ │
|
||||
│ │ • Changes are transient │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Reboot or Unmount │ │
|
||||
│ │ │ │
|
||||
│ │ • Reboot: Auto-restore to read-only │ │
|
||||
│ │ • Unmount: Manual restore to read-only │ │
|
||||
│ │ • All changes discarded │ │
|
||||
│ │ • Return to initial state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Filesystem Impact
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Filesystem Impact │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Before Overlay │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ /usr │ │ /etc │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Read-only │ │ • Writable │ │
|
||||
│ │ • Immutable │ │ • Persistent │ │
|
||||
│ │ • Base system │ │ • Configuration │ │
|
||||
│ │ • OSTree │ │ • Not affected by overlay │ │
|
||||
│ │ managed │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ /var │ │
|
||||
│ │ │ │
|
||||
│ │ • Writable │ │
|
||||
│ │ • Persistent │ │
|
||||
│ │ • Runtime data │ │
|
||||
│ │ • Not affected by overlay │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ After Overlay │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ /usr │ │ /etc │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Writable │ │ • Writable │ │
|
||||
│ │ • Overlay │ │ • Persistent │ │
|
||||
│ │ • Transient │ │ • Configuration │ │
|
||||
│ │ • Changes │ │ • Not affected by overlay │ │
|
||||
│ │ discarded │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ /var │ │
|
||||
│ │ │ │
|
||||
│ │ • Writable │ │
|
||||
│ │ • Persistent │ │
|
||||
│ │ • Runtime data │ │
|
||||
│ │ • Not affected by overlay │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc usr-overlay process, showing all decision points, operations, and filesystem changes involved in creating and managing a transient writable overlay on the `/usr` directory.
|
||||
628
usr-overlay/bootc-usr-overlay-technical-guide.md
Normal file
628
usr-overlay/bootc-usr-overlay-technical-guide.md
Normal file
|
|
@ -0,0 +1,628 @@
|
|||
# bootc usr-overlay - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc usr-overlay` is a command for adding a transient writable overlay filesystem on the `/usr` directory. This overlay allows temporary modifications to the `/usr` directory that will be discarded on reboot, enabling package installation and system modifications while maintaining the integrity of the base system.
|
||||
|
||||
## Purpose
|
||||
|
||||
The usr-overlay command serves several critical functions:
|
||||
|
||||
1. **Temporary Package Installation**: Install packages that aren't in the base image
|
||||
2. **Debugging Tools**: Install tracing and debugging tools like `strace`
|
||||
3. **System Modifications**: Make temporary changes to `/usr` without persistence
|
||||
4. **Development Workflows**: Enable development and testing workflows
|
||||
5. **System Maintenance**: Allow maintenance operations without permanent changes
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc usr-overlay [OPTIONS...]
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Add transient writable overlay on /usr
|
||||
bootc usr-overlay
|
||||
|
||||
# Alternative command name
|
||||
bootc usroverlay
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
Currently, `bootc usr-overlay` has no command-line options. It's a simple command that either succeeds or fails.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 1. Implementation Structure
|
||||
|
||||
```rust
|
||||
/// Implementation of `bootc usroverlay`
|
||||
async fn usroverlay() -> Result<()> {
|
||||
// This is just a pass-through today. At some point we may make this a libostree API
|
||||
// or even oxidize it.
|
||||
Err(Command::new("ostree")
|
||||
.args(["admin", "unlock"])
|
||||
.exec()
|
||||
.into())
|
||||
}
|
||||
```
|
||||
|
||||
**Current Implementation**:
|
||||
- **Pass-through Command**: Currently delegates to `ostree admin unlock`
|
||||
- **Future Plans**: May become a native libostree API or Rust implementation
|
||||
- **Simple Interface**: No complex options or configuration
|
||||
|
||||
### 2. OSTree Integration
|
||||
|
||||
The command currently uses `ostree admin unlock` which:
|
||||
- **Unlocks the OSTree deployment**: Makes `/usr` writable
|
||||
- **Creates Overlay**: Sets up a transient overlay filesystem
|
||||
- **Preserves Base**: Keeps the original `/usr` intact
|
||||
- **Enables Modifications**: Allows temporary changes
|
||||
|
||||
### 3. Overlay Filesystem Mechanism
|
||||
|
||||
```bash
|
||||
# What happens internally (simplified)
|
||||
ostree admin unlock
|
||||
# This creates an overlay filesystem on /usr
|
||||
# - Lower layer: Original read-only /usr
|
||||
# - Upper layer: Writable overlay
|
||||
# - Work layer: Temporary files during operations
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Debugging and Tracing Tools
|
||||
|
||||
**Scenario**: Need to install debugging tools not in base image
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install debugging tools
|
||||
apt update
|
||||
apt install -y strace gdb valgrind
|
||||
|
||||
# Use tools
|
||||
strace -p 1234
|
||||
gdb /path/to/process
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
### 2. Package Manager Operations
|
||||
|
||||
**Scenario**: Install packages temporarily for testing
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install packages
|
||||
apt install -y python3-pip
|
||||
pip3 install requests
|
||||
|
||||
# Test application
|
||||
python3 -c "import requests; print('Success')"
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
### 3. Development Workflows
|
||||
|
||||
**Scenario**: Development and testing without permanent changes
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install development tools
|
||||
apt install -y build-essential git
|
||||
|
||||
# Clone and build project
|
||||
git clone https://github.com/user/project.git
|
||||
cd project
|
||||
make
|
||||
|
||||
# Test and develop
|
||||
./project
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
### 4. System Maintenance
|
||||
|
||||
**Scenario**: Temporary system modifications for maintenance
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install maintenance tools
|
||||
apt install -y htop iotop nethogs
|
||||
|
||||
# Perform maintenance
|
||||
htop
|
||||
iotop
|
||||
nethogs
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
## Filesystem Behavior
|
||||
|
||||
### 1. /usr Directory
|
||||
|
||||
**Before Overlay**:
|
||||
- **Read-only**: `/usr` is mounted read-only
|
||||
- **Immutable**: Cannot be modified
|
||||
- **Base System**: Contains original system files
|
||||
|
||||
**After Overlay**:
|
||||
- **Writable**: `/usr` becomes writable
|
||||
- **Overlay**: Changes go to overlay layer
|
||||
- **Transient**: Changes discarded on reboot
|
||||
|
||||
### 2. /etc and /var Directories
|
||||
|
||||
**Important**: The overlay only affects `/usr`, not `/etc` or `/var`
|
||||
|
||||
**/etc Directory**:
|
||||
- **Persistent**: Changes persist across reboots
|
||||
- **Configuration**: System configuration files
|
||||
- **Not Affected**: Overlay doesn't apply here
|
||||
|
||||
**/var Directory**:
|
||||
- **Persistent**: Changes persist across reboots
|
||||
- **Runtime Data**: Logs, caches, temporary files
|
||||
- **Not Affected**: Overlay doesn't apply here
|
||||
|
||||
### 3. Overlay Structure
|
||||
|
||||
```
|
||||
/usr (overlay mount point)
|
||||
├── lower (original read-only /usr)
|
||||
├── upper (writable overlay layer)
|
||||
└── work (temporary work directory)
|
||||
```
|
||||
|
||||
## OSTree Integration
|
||||
|
||||
### 1. OSTree Admin Unlock
|
||||
|
||||
The command delegates to `ostree admin unlock` which:
|
||||
|
||||
```bash
|
||||
ostree admin unlock
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- **Unlocks Deployment**: Makes the current deployment writable
|
||||
- **Creates Overlay**: Sets up overlay filesystem
|
||||
- **Preserves Base**: Keeps original content intact
|
||||
- **Enables Changes**: Allows modifications
|
||||
|
||||
### 2. OSTree Deployment State
|
||||
|
||||
**Before Unlock**:
|
||||
- **Read-only**: Deployment is read-only
|
||||
- **Immutable**: Cannot be modified
|
||||
- **Base State**: Original system state
|
||||
|
||||
**After Unlock**:
|
||||
- **Writable**: Deployment becomes writable
|
||||
- **Overlay Active**: Overlay filesystem active
|
||||
- **Changes Allowed**: Modifications possible
|
||||
|
||||
### 3. OSTree Lock Management
|
||||
|
||||
**Lock States**:
|
||||
- **Locked**: Read-only, immutable
|
||||
- **Unlocked**: Writable, overlay active
|
||||
- **Auto-lock**: Locks on reboot
|
||||
|
||||
## Package Manager Integration
|
||||
|
||||
### 1. APT Integration
|
||||
|
||||
**Debian/Ubuntu Systems**:
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Update package lists
|
||||
apt update
|
||||
|
||||
# Install packages
|
||||
apt install -y package-name
|
||||
|
||||
# Packages installed to overlay
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
**Package Installation**:
|
||||
- **Overlay Target**: Packages installed to overlay
|
||||
- **Transient**: Changes don't persist
|
||||
- **Base Preserved**: Original system unchanged
|
||||
|
||||
### 2. DNF Integration
|
||||
|
||||
**Fedora/RHEL Systems**:
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install packages
|
||||
dnf install -y package-name
|
||||
|
||||
# Packages installed to overlay
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
**Package Installation**:
|
||||
- **Overlay Target**: Packages installed to overlay
|
||||
- **Transient**: Changes don't persist
|
||||
- **Base Preserved**: Original system unchanged
|
||||
|
||||
### 3. Package Manager Detection
|
||||
|
||||
**Recommended Integration**:
|
||||
Package managers should detect overlay state and inform users:
|
||||
|
||||
```bash
|
||||
# Example error message
|
||||
error: read-only /usr detected, refusing to operate.
|
||||
See `man apt-image-based` for more information.
|
||||
```
|
||||
|
||||
**Detection Methods**:
|
||||
- **Read-only Check**: Check if `/usr` is read-only
|
||||
- **Overlay Detection**: Detect overlay filesystem
|
||||
- **Bootc Detection**: Check if system is bootc-managed
|
||||
|
||||
## Unmounting the Overlay
|
||||
|
||||
### 1. Lazy Unmount
|
||||
|
||||
**Standard Unmount**:
|
||||
```bash
|
||||
umount /usr
|
||||
# May fail if processes hold references
|
||||
```
|
||||
|
||||
**Lazy Unmount**:
|
||||
```bash
|
||||
umount -l /usr
|
||||
# Unmounts when references are released
|
||||
```
|
||||
|
||||
### 2. Process References
|
||||
|
||||
**Common Holders**:
|
||||
- **Package Managers**: `apt`, `dnf` processes
|
||||
- **System Services**: Services using `/usr` files
|
||||
- **User Processes**: Applications with open files
|
||||
|
||||
**Solution**:
|
||||
- **Lazy Unmount**: Use `umount -l /usr`
|
||||
- **Process Termination**: Stop processes holding references
|
||||
- **Reboot**: Automatic unmount on reboot
|
||||
|
||||
### 3. Unmount Process
|
||||
|
||||
```bash
|
||||
# Check what's using /usr
|
||||
lsof /usr
|
||||
|
||||
# Lazy unmount
|
||||
umount -l /usr
|
||||
|
||||
# Verify unmount
|
||||
mount | grep /usr
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Common Errors
|
||||
|
||||
#### OSTree Not Available
|
||||
```bash
|
||||
Error: ostree command not found
|
||||
```
|
||||
|
||||
**Solution**: Install OSTree
|
||||
```bash
|
||||
apt install -y ostree
|
||||
# or
|
||||
dnf install -y ostree
|
||||
```
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
Error: Permission denied
|
||||
```
|
||||
|
||||
**Solution**: Run with appropriate privileges
|
||||
```bash
|
||||
sudo bootc usr-overlay
|
||||
```
|
||||
|
||||
#### Already Unlocked
|
||||
```bash
|
||||
Error: Deployment already unlocked
|
||||
```
|
||||
|
||||
**Solution**: Check current state
|
||||
```bash
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
### 2. Troubleshooting
|
||||
|
||||
#### Check Overlay Status
|
||||
```bash
|
||||
# Check if overlay is active
|
||||
mount | grep overlay
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check /usr mount
|
||||
mount | grep /usr
|
||||
```
|
||||
|
||||
#### Verify Changes
|
||||
```bash
|
||||
# Test if /usr is writable
|
||||
touch /usr/test-file
|
||||
|
||||
# Check if file exists
|
||||
ls -la /usr/test-file
|
||||
|
||||
# File should exist until reboot
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Transient Nature
|
||||
|
||||
**Security Benefits**:
|
||||
- **No Persistence**: Changes don't persist
|
||||
- **Base Integrity**: Original system unchanged
|
||||
- **Clean State**: System returns to known state
|
||||
|
||||
**Security Implications**:
|
||||
- **Temporary Access**: Allows temporary modifications
|
||||
- **Package Installation**: Can install arbitrary packages
|
||||
- **System Changes**: Can modify system behavior
|
||||
|
||||
### 2. Access Control
|
||||
|
||||
**Privilege Requirements**:
|
||||
- **Root Access**: Requires root privileges
|
||||
- **OSTree Access**: Needs OSTree admin access
|
||||
- **Mount Privileges**: Requires mount capabilities
|
||||
|
||||
**Best Practices**:
|
||||
- **Minimal Use**: Use only when necessary
|
||||
- **Audit Changes**: Monitor what's installed
|
||||
- **Clean Up**: Unmount when done
|
||||
|
||||
### 3. Overlay Security
|
||||
|
||||
**Overlay Isolation**:
|
||||
- **Separate Layer**: Changes in separate layer
|
||||
- **Base Protection**: Original system protected
|
||||
- **Clean Separation**: Clear boundary between layers
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Overlay Overhead
|
||||
|
||||
**Performance Impact**:
|
||||
- **Overlay Layer**: Additional filesystem layer
|
||||
- **Copy-on-Write**: COW operations for modifications
|
||||
- **Metadata Overhead**: Additional metadata for overlay
|
||||
|
||||
**Mitigation**:
|
||||
- **Minimal Changes**: Make only necessary changes
|
||||
- **Unmount When Done**: Remove overlay when not needed
|
||||
- **Efficient Operations**: Use efficient package operations
|
||||
|
||||
### 2. Storage Usage
|
||||
|
||||
**Storage Impact**:
|
||||
- **Overlay Storage**: Additional storage for overlay
|
||||
- **Temporary Files**: Work directory usage
|
||||
- **Package Caches**: Package manager caches
|
||||
|
||||
**Management**:
|
||||
- **Clean Caches**: Clean package caches
|
||||
- **Unmount Overlay**: Remove overlay when done
|
||||
- **Monitor Usage**: Monitor storage usage
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### 1. Development Workflows
|
||||
|
||||
**Development Setup**:
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install development tools
|
||||
apt install -y build-essential git python3-pip
|
||||
|
||||
# Install project dependencies
|
||||
pip3 install -r requirements.txt
|
||||
|
||||
# Develop and test
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
### 2. Debugging Workflows
|
||||
|
||||
**Debugging Setup**:
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install debugging tools
|
||||
apt install -y strace gdb valgrind
|
||||
|
||||
# Debug application
|
||||
strace -f ./application
|
||||
gdb ./application
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
### 3. Testing Workflows
|
||||
|
||||
**Testing Setup**:
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install test tools
|
||||
apt install -y test-package
|
||||
|
||||
# Run tests
|
||||
./run-tests.sh
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Usage Guidelines
|
||||
|
||||
**When to Use**:
|
||||
- **Debugging**: Install debugging tools
|
||||
- **Development**: Temporary development setup
|
||||
- **Testing**: Test new packages
|
||||
- **Maintenance**: System maintenance tasks
|
||||
|
||||
**When Not to Use**:
|
||||
- **Production**: Avoid in production systems
|
||||
- **Persistent Changes**: Don't use for permanent changes
|
||||
- **System Modifications**: Avoid core system changes
|
||||
|
||||
### 2. Workflow Management
|
||||
|
||||
**Before Overlay**:
|
||||
- **Plan Changes**: Know what you need to install
|
||||
- **Check Dependencies**: Verify package dependencies
|
||||
- **Prepare Commands**: Have commands ready
|
||||
|
||||
**During Overlay**:
|
||||
- **Minimal Changes**: Make only necessary changes
|
||||
- **Document Changes**: Keep track of what's installed
|
||||
- **Test Thoroughly**: Test all functionality
|
||||
|
||||
**After Overlay**:
|
||||
- **Clean Up**: Remove unnecessary packages
|
||||
- **Unmount**: Unmount overlay when done
|
||||
- **Document**: Document what was done
|
||||
|
||||
### 3. System Management
|
||||
|
||||
**Monitoring**:
|
||||
- **Check Status**: Monitor overlay status
|
||||
- **Track Changes**: Keep track of modifications
|
||||
- **Monitor Performance**: Watch for performance impact
|
||||
|
||||
**Maintenance**:
|
||||
- **Regular Cleanup**: Clean up regularly
|
||||
- **Unmount When Done**: Remove overlay when not needed
|
||||
- **Reboot Periodically**: Reboot to clean state
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
**Native Implementation**:
|
||||
- **Rust Implementation**: Native Rust implementation
|
||||
- **libostree API**: Direct libostree API usage
|
||||
- **Better Integration**: Improved OSTree integration
|
||||
|
||||
**Enhanced Functionality**:
|
||||
- **Selective Overlay**: Overlay specific directories
|
||||
- **Persistent Overlay**: Option for persistent overlays
|
||||
- **Overlay Management**: Better overlay management
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
**Package Manager Integration**:
|
||||
- **Automatic Detection**: Auto-detect overlay state
|
||||
- **User Warnings**: Warn about transient changes
|
||||
- **Better Error Messages**: Improved error messages
|
||||
|
||||
**System Integration**:
|
||||
- **Service Integration**: Systemd service integration
|
||||
- **Configuration**: Configuration file support
|
||||
- **Logging**: Better logging and monitoring
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### Overlay Not Working
|
||||
```bash
|
||||
# Check if overlay is active
|
||||
mount | grep overlay
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check /usr mount
|
||||
mount | grep /usr
|
||||
```
|
||||
|
||||
#### Package Installation Fails
|
||||
```bash
|
||||
# Check if /usr is writable
|
||||
touch /usr/test-file
|
||||
|
||||
# Check package manager status
|
||||
apt update
|
||||
# or
|
||||
dnf check-update
|
||||
```
|
||||
|
||||
#### Cannot Unmount
|
||||
```bash
|
||||
# Check what's using /usr
|
||||
lsof /usr
|
||||
|
||||
# Use lazy unmount
|
||||
umount -l /usr
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Check overlay status
|
||||
mount | grep overlay
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check /usr mount
|
||||
mount | grep /usr
|
||||
|
||||
# Check processes using /usr
|
||||
lsof /usr
|
||||
|
||||
# Check overlay filesystem
|
||||
cat /proc/mounts | grep overlay
|
||||
```
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc usr-overlay system's architecture, implementation, and usage patterns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue