deb-bootupd/README.md

deb-bootupd

A Debian-compatible fork of bootupd for immutable Debian systems.

Project Overview

deb-bootupd is a sophisticated, production-ready Rust-based CLI tool that provides cross-distribution, OS update system agnostic bootloader management capabilities. It addresses a critical gap in Linux system management by handling bootloader updates consistently across different distributions and update mechanisms.

This fork specifically adapts the original Red Hat/Fedora-centric bootupd for Debian-based immutable systems using OSTree and bootc, making it possible to create immutable Debian distributions like particle-os.

Key Features

• Single Binary, Multicall Architecture: The same executable serves as both bootupd and bootupctl
• Component-Based Design: Pluggable architecture supporting EFI, BIOS, and other bootloader types
• OSTree Integration: Full support for Debian OSTree immutable systems
• Debian Package System: Native DPKG/APT integration instead of RPM
• Cross-Architecture Support: x86_64, aarch64, riscv64, powerpc64
• Bootloader Support: GRUB, shim, systemd-boot detection
• State Persistence: Robust state management across OSTree deployments

Architecture

Core Components

• EFI Component: UEFI bootloader management with automatic ESP detection
• BIOS Component: Traditional BIOS/MBR bootloader support
• OSTree Integration: Seamless integration with Debian OSTree deployments
• Package System: DPKG-based package metadata discovery
• State Management: Persistent state tracking in /boot/bootupd-state.json

Design Philosophy

• No Daemon: Despite the 'd' suffix, it's "bootloader-upDater" not "bootloader-updater-Daemon"
• systemd Integration: Uses systemd-run for robust locking and sandboxing
• Safety First: Comprehensive error handling and rollback capabilities
• Distribution Agnostic: Core architecture works across different Linux distributions

Installation

Prerequisites

• Debian-based system (Debian, Ubuntu, etc.)
• Rust toolchain (for building from source)
• Required system packages:
  • efibootmgr (for EFI systems)
  • grub-common (for GRUB support)
  • mount/umount (standard Linux tools)

Building from Source

# Clone the repository
git clone https://git.raines.xyz/robojerk/deb-bootupd.git
cd deb-bootupd

# Build the project
cargo build --release

# Install (requires root)
sudo cargo install --path .

Debian Package

# Build Debian package
dpkg-buildpackage -b

# Install package
sudo dpkg -i ../deb-bootupd_*.deb

Usage

Basic Commands

# Check system status
bootupctl status

# Update all bootloader components
bootupctl update

# Adopt existing bootloaders and update them
bootupctl adopt-and-update

# Validate system state
bootupctl validate

Advanced Operations

# Generate update metadata (for image builders)
bootupd generate-update-metadata

# Install bootloader components
bootupd install --src-root /path/to/source --dest-root /path/to/destination

OSTree Integration

deb-bootupd is specifically designed for Debian OSTree immutable systems:

• Image-based Updates: Updates come from new bootc images, not traditional package repositories
• Deployment Coordination: Works seamlessly with OSTree deployment system
• State Persistence: Bootloader state survives across OSTree deployments
• Rollback Support: Leverages OSTree's built-in rollback capabilities

Particle-OS Integration

This fork is specifically designed to work with particle-os, a Debian-based immutable distribution:

• Hybrid Approach: Debian packages within immutable OSTree structure
• Bootc Integration: Full integration with bootc image builder
• Debian Conventions: Follows Debian filesystem and package conventions

Configuration

State File Location

• State File: /boot/bootupd-state.json
• Lock File: /run/bootupd-lock
• Updates Directory: /usr/lib/bootupd/updates

Component Configuration

Components are automatically detected and configured based on your system:

• EFI Systems: Automatic ESP detection and UEFI boot entry management
• BIOS Systems: Direct MBR manipulation for traditional bootloaders
• Hybrid Systems: Support for both EFI and BIOS configurations

Development

Project Structure

deb-bootupd/
├── src/                    # Source code
│   ├── efi.rs             # EFI component implementation
│   ├── bios.rs            # BIOS component implementation
│   ├── ostreeutil.rs      # OSTree integration
│   ├── packagesystem.rs   # DPKG package system integration
│   └── ...
├── systemd/               # Systemd service files
├── tests/                 # Test suite
├── Cargo.toml            # Rust dependencies
└── debian/               # Debian packaging files

Key Adaptations from Upstream

1. Package System: Replaced RPM with DPKG/APT integration
2. OS Detection: Enhanced for Debian family distributions
3. Path Conventions: Adapted for Debian filesystem standards
4. OSTree Integration: Optimized for Debian OSTree deployments

Building and Testing

# Run tests
cargo test

# Run with specific features
cargo test --features integration

# Check code quality
cargo clippy
cargo fmt

Troubleshooting

Common Issues

1. Permission Denied: Ensure you're running with root privileges
2. EFI Not Detected: Verify efibootmgr is installed and EFI is enabled
3. OSTree Integration: Check that OSTree is properly configured
4. Package Queries: Ensure DPKG database is accessible

Debug Mode

# Enable debug logging
RUST_LOG=debug bootupctl status

# Check system state
cat /boot/bootupd-state.json

Contributing

We welcome contributions! This project is a proof-of-concept for immutable Debian systems.

Development Priorities

1. Core Functionality: Ensure basic bootloader management works on Debian
2. OSTree Integration: Optimize for Debian OSTree deployments
3. Testing: Comprehensive test coverage for Debian environments
4. Documentation: Clear guides for users and developers

License

This project is licensed under the same terms as the original bootupd project. See the LICENSE file for details.

Acknowledgments

• Original bootupd: CoreOS bootupd - The excellent foundation this project builds upon
• ublue-os: For pioneering immutable Debian distributions
• Debian Community: For the robust package system and distribution standards

Roadmap

• Initial Debian Adaptation: Basic DPKG integration
• OSTree Support: Integration with Debian OSTree systems
• Enhanced Testing: Comprehensive test suite for Debian environments
• Production Readiness: Full validation and stability testing
• Community Adoption: Integration with particle-os and other Debian immutable distributions

Support

• Issues: Report bugs and feature requests via GitLab issues
• Discussions: Join the conversation in GitLab discussions
• Documentation: Check this README and inline code documentation

---

Note: This is a proof-of-concept project. While it's designed to be production-ready, it's primarily intended to demonstrate the feasibility of immutable Debian systems using ublue-os tools.