deb-bootupd/README.md

# deb-bootupd

Debian adaptation of the `bootupd` project for immutable Debian systems.

<!-- Last workflow test: 2025-08-10 01:19 PDT - Testing networking fixes -->

## Summary

**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](https://github.com/ublue-os/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`

### Binary Architecture

- **`bootupd`**: The main binary that performs bootloader updates (NOT a daemon)
- **`bootupctl`**: A symlink to the main `bootupd` binary (multicall binary pattern)
- **Relationship**: Both are the same binary, with `bootupctl` being a symlink. The binary detects which name it was called as and behaves accordingly.

### 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

### Installation Methods

**1. Debian Package (Recommended)**
- **Pros**: No compilation, automatic dependency resolution, system integration
- **Use when**: You want to install and run immediately, or for production systems
- **Requirements**: Just `apt` and root access

**2. Pre-built .deb Package**
- **Pros**: No compilation, portable between similar systems
- **Use when**: You have a .deb file but no repository access
- **Requirements**: `dpkg` and root access

**3. Build from Source**
- **Pros**: Latest development version, customization options
- **Use when**: Developing, testing, or need specific features
- **Requirements**: Rust toolchain, build dependencies, more time

**4. Build Your Own .deb Package**
- **Pros**: Customizable, distributable, reproducible
- **Use when**: Creating packages for distribution or custom builds
- **Requirements**: Build dependencies, packaging knowledge

### Prerequisites

**For Package Installation (Methods 1-2)**:
- Debian-based system (Debian, Ubuntu, etc.)
- `apt` package manager
- Root access for installation

**For Source Building (Methods 3-4)**:
- Debian-based system (Debian, Ubuntu, etc.)
- Rust toolchain (rustc, cargo)
- Build dependencies (see below)

**Required Runtime Packages** (installed automatically with .deb):
- `efibootmgr` (for EFI systems)
- `grub-common` (for GRUB support)
- `mount`/`umount` (standard Linux tools)

### Debian Package (Recommended - No Compilation Required)

```bash
# Install from Debian repository (when available)
sudo apt update
sudo apt install deb-bootupd

# Or install from a pre-built .deb package
sudo dpkg -i deb-bootupd_*.deb

# If dependencies are missing, install them
sudo apt install -f
```

### Building from Source

```bash
# 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 .
```

### Running as Rust Script (Development)

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

# Run directly without installing (development mode)
cargo run -- status                    # Run bootupctl status
cargo run -- update                    # Run bootupctl update
cargo run -- adopt-and-update         # Run bootupctl adopt-and-update

# Run with specific binary name (multicall binary)
cargo run --bin bootupd -- status     # Run as bootupd binary
cargo run --bin bootupctl -- status   # Run as bootupctl binary

# Run with debug output
RUST_LOG=debug cargo run -- status

# Run with custom log level
RUST_LOG=info cargo run -- status

# Run specific tests
cargo test                            # Run all tests
cargo test --package deb-bootupd      # Run package tests
cargo test --test integration         # Run integration tests

# Development workflow
cargo check                           # Check compilation without building
cargo clippy                          # Run linter
cargo fmt --check                     # Check code formatting
cargo fmt                             # Auto-format code
```

### How the Multicall Binary Works

deb-bootupd uses a **multicall binary pattern** - a single Rust executable that behaves differently based on how it's called:

```bash
# When called as 'bootupd' (main binary)
cargo run --bin bootupd -- install --src-root /src --dest-root /dest

# When called as 'bootupctl' (CLI interface)
cargo run --bin bootupctl -- status
cargo run --bin bootupctl -- update

# The binary detects argv[0] and switches behavior accordingly
```

**Benefits for Development:**
- **Single codebase**: All functionality in one Rust project
- **Easy testing**: Test both modes from one source
- **Consistent behavior**: Same binary, different interfaces
- **Simplified deployment**: One executable to install

### Building Your Own Debian Package

```bash
# Install build dependencies
sudo apt install build-essential dh-cargo rustc cargo pkg-config libssl-dev libsystemd-dev

# Build Debian package
dpkg-buildpackage -b

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

## Quick Start

### Install and Run (No Compilation)

```bash
# 1. Install the package (when available in repositories)
sudo apt update && sudo apt install deb-bootupd

# 2. Check if it's working
bootupctl status

# 3. You're ready to use deb-bootupd!
```

### Automated Builds with Forgejo Actions

This repository includes Forgejo Actions workflows for automated building and artifact management:

- **`.forgejo/workflows/build-artifacts.yml`** - Full build pipeline with Forgejo Package Registry upload
- **`.forgejo/workflows/simple-build.yml`** - Simple build with artifact upload

**Setup Requirements:**
1. Add `ACCESS_TOKEN` secret to repository settings
2. Token needs `repo` and `write:packages` permissions
3. Workflows trigger on push/PR to main/master branches

**What Gets Built:**
- Rust binaries (release mode)
- Source code artifacts
- Debian packaging files
- Systemd service files

## Usage

### Basic Commands

```bash
# 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

```bash
# 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](https://github.com/ublue-os/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

```bash
# 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

```bash
# 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](https://github.com/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

- [x] **Initial Debian Adaptation**: Basic DPKG integration
- [x] **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.
# Test workflow trigger - Sun Aug 10 08:53:24 AM PDT 2025