# deb-bootupd

A Debian-compatible fork of [bootupd](https://github.com/coreos/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](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`

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

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

### Debian Package

```bash
# Build Debian package
dpkg-buildpackage -b

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

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