197 lines
No EOL
7.8 KiB
Markdown
197 lines
No EOL
7.8 KiB
Markdown
# Debian OSTree Boot Examples Report
|
|
|
|
## Overview
|
|
|
|
The Debian OSTree boot examples provide a comprehensive framework for testing and implementing OSTree-based bootable systems on Debian. OSTree is a versioning system for operating system root filesystems that enables atomic upgrades, rollbacks, and parallel installations of different OS versions. This collection of files demonstrates how to convert an existing Debian system to use OSTree for immutable, atomic system management.
|
|
|
|
## File Analysis
|
|
|
|
### 1. README.md - Setup and Testing Instructions
|
|
|
|
The README provides detailed instructions for testing OSTree boot functionality on an existing Debian system. The process involves converting a traditional Debian installation to an OSTree-managed system.
|
|
|
|
**Key Requirements:**
|
|
- AMD64 system running Debian 10 or later
|
|
- Unencrypted root partition
|
|
- GRUB with BIOS booting
|
|
- Separate /boot partition (for Debian 10 and older systems with OSTree 2020.5 or earlier)
|
|
|
|
**Installation Process Example:**
|
|
```bash
|
|
# Install required packages
|
|
apt-get install ostree ostree-boot multistrap
|
|
|
|
# Initialize OSTree system repository
|
|
ostree admin init-fs /
|
|
ostree admin os-init debian
|
|
|
|
# Build OSTree commits using the builder scripts
|
|
./deb-ostree-builder ./ostree-1.conf sid-1 /ostree/repo
|
|
./deb-ostree-builder ./ostree-2.conf sid-2 /ostree/repo
|
|
|
|
# Deploy the first commit
|
|
ostree admin deploy --karg-proc-cmdline --os=debian os/debian/amd64/sid-1
|
|
```
|
|
|
|
The README demonstrates the atomic nature of OSTree by showing how to deploy two different commits (with and without the `hello` package) and switch between them through reboots.
|
|
|
|
### 2. deb-ostree-builder - Core Build Script
|
|
|
|
This bash script is the primary tool for building bootable Debian OSTree commits. It orchestrates the entire process from system construction to OSTree repository commitment.
|
|
|
|
**Key Features:**
|
|
- Uses `multistrap` for system construction
|
|
- Supports multiple architectures (defaults to current system architecture)
|
|
- Includes GPG signing capabilities for secure deployments
|
|
- Implements comprehensive cleanup and error handling
|
|
|
|
**Core Functionality:**
|
|
```bash
|
|
# Architecture detection
|
|
ARCH=$(dpkg --print-architecture)
|
|
|
|
# OSTree-specific preparations
|
|
# - Configures dracut for generic initramfs
|
|
# - Prevents daemon startup during build
|
|
# - Mounts necessary filesystems for chroot operations
|
|
```
|
|
|
|
**OSTree Compatibility Transformations:**
|
|
- Moves `/etc` to `/usr/etc` (OSTree three-way merge requirement)
|
|
- Relocates dpkg database to `/usr/share/dpkg/database` with symlink
|
|
- Creates persistent directory symlinks (`/home` → `/sysroot/home`)
|
|
- Renames kernel and initramfs files with OSTree-required checksums
|
|
- Configures tmpfiles.d for persistent directories
|
|
|
|
### 3. modified-deb-ostree-builder - Enhanced Build Script
|
|
|
|
This version extends the original builder with additional package installation capabilities.
|
|
|
|
**Key Modification:**
|
|
```bash
|
|
# Extra package installation from /root/extra-packages
|
|
if [ -d /root/extra-packages ]; then
|
|
mkdir "$BUILDDIR/root/extra-packages"
|
|
cp /root/extra-packages/*.deb "$BUILDDIR/root/extra-packages"
|
|
chroot "$BUILDDIR" apt -y install /root/extra-packages/*.deb
|
|
fi
|
|
```
|
|
|
|
This enhancement allows testing of packages not yet in the official Debian archive, making it particularly useful for testing OSTree boot functionality before official release.
|
|
|
|
### 4. ostree-1.conf - Base System Configuration
|
|
|
|
This multistrap configuration defines a minimal OSTree-compatible Debian system.
|
|
|
|
**Package Selection:**
|
|
- `linux-image-amd64` - Kernel for AMD64 architecture
|
|
- `grub-pc` - GRUB bootloader for PC/BIOS systems
|
|
- `dracut` - Initramfs generation tool
|
|
- `ostree-boot` - OSTree boot integration
|
|
- `lvm2` - Logical Volume Manager support
|
|
- `usrmerge` - Required for OSTree compatibility
|
|
|
|
**Configuration Details:**
|
|
```ini
|
|
[debian]
|
|
source=http://deb.debian.org/debian
|
|
keyring=debian-archive-keyring
|
|
suite=sid
|
|
```
|
|
|
|
This creates a baseline system suitable for OSTree deployment without additional packages.
|
|
|
|
### 5. ostree-2.conf - Extended System Configuration
|
|
|
|
Identical to ostree-1.conf but includes an additional package for testing deployment differences.
|
|
|
|
**Additional Package:**
|
|
- `hello` - Simple test package that provides the `hello` command
|
|
|
|
This configuration demonstrates OSTree's ability to manage different system states and allows verification that deployments are working correctly by testing for the presence/absence of the hello command.
|
|
|
|
## Technical Implementation Details
|
|
|
|
### OSTree Filesystem Layout
|
|
|
|
The builder scripts implement OSTree's required filesystem layout:
|
|
|
|
**Persistent Directories (survive updates):**
|
|
- `/sysroot/home` - User home directories
|
|
- `/sysroot/root` - Root user home
|
|
- `/var/opt` and `/var/local` - Optional and local variable data
|
|
|
|
**Immutable Directories (part of OSTree commit):**
|
|
- `/usr` - All system programs and libraries
|
|
- `/usr/etc` - System configuration (managed via three-way merge)
|
|
|
|
### Boot Management
|
|
|
|
OSTree requires specific boot file naming conventions:
|
|
```bash
|
|
# Combined checksum of kernel and initramfs
|
|
csum=$(cat vmlinuz-* initrd.img-* | sha256sum --binary | awk '{print $1}')
|
|
|
|
# Rename files with checksum suffix
|
|
mv vmlinuz-* vmlinuz-*-${csum}
|
|
mv initrd.img-* initramfs-*-${csum}
|
|
```
|
|
|
|
This ensures boot file integrity and enables OSTree's atomic boot management.
|
|
|
|
### Package Management Integration
|
|
|
|
The scripts handle Debian package management compatibility:
|
|
- Relocates dpkg database to `/usr/share/dpkg/database`
|
|
- Creates symlink from traditional location (`/var/lib/dpkg`)
|
|
- Preserves package management functionality in OSTree environment
|
|
|
|
## Use Cases and Benefits
|
|
|
|
### Atomic System Updates
|
|
OSTree enables atomic system updates where either the entire update succeeds or fails completely, eliminating partially updated systems.
|
|
|
|
### Rollback Capability
|
|
Users can instantly rollback to previous deployments if issues arise with new updates.
|
|
|
|
### Parallel Deployments
|
|
Multiple system versions can exist simultaneously, allowing for safe testing and gradual transitions.
|
|
|
|
### Immutable Infrastructure
|
|
The read-only nature of the root filesystem enhances security and system reliability.
|
|
|
|
## Example Workflow
|
|
|
|
1. **Initial Setup**: Convert existing Debian system to OSTree management
|
|
2. **Build Base System**: Create initial OSTree commit using `ostree-1.conf`
|
|
3. **Deploy and Test**: Deploy base system and verify functionality
|
|
4. **Create Updated Version**: Build enhanced system using `ostree-2.conf`
|
|
5. **Atomic Upgrade**: Deploy new version alongside existing installation
|
|
6. **Verification**: Test new functionality (hello command availability)
|
|
7. **Rollback if Needed**: Return to previous version if issues occur
|
|
|
|
## System Architecture
|
|
|
|
The OSTree boot examples implement a sophisticated system architecture that separates mutable and immutable components:
|
|
|
|
**Immutable Components:**
|
|
- Operating system binaries and libraries in `/usr`
|
|
- System configuration in `/usr/etc`
|
|
- Boot files with integrity checksums
|
|
|
|
**Mutable Components:**
|
|
- User data in `/sysroot/home`
|
|
- System state in `/var` (recreated per boot)
|
|
- Runtime configuration overlays
|
|
|
|
This architecture provides the foundation for reliable, maintainable system deployments while preserving the flexibility needed for system administration and user data management.
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
1. [README.md](https://salsa.debian.org/debian/ostree/-/raw/debian/latest/debian/ostree-boot-examples/README.md)
|
|
2. [deb-ostree-builder](https://salsa.debian.org/debian/ostree/-/raw/debian/latest/debian/ostree-boot-examples/deb-ostree-builder)
|
|
3. [modified-deb-ostree-builder](https://salsa.debian.org/debian/ostree/-/raw/debian/latest/debian/ostree-boot-examples/modified-deb-ostree-builder)
|
|
4. [ostree-1.conf](https://salsa.debian.org/debian/ostree/-/raw/debian/latest/debian/ostree-boot-examples/ostree-1.conf)
|
|
5. [ostree-2.conf](https://salsa.debian.org/debian/ostree/-/raw/debian/latest/debian/ostree-boot-examples/ostree-2.conf) |