Restructure project layout for better CI/CD integration
- Flattened nested bootupd/bootupd/ structure to root level - Moved all core project files to root directory - Added proper Debian packaging structure (debian/ directory) - Created build scripts and CI configuration - Improved project organization for CI/CD tools - All Rust source, tests, and configuration now at root level - Added GitHub Actions workflow for automated testing - Maintained all original functionality while improving structure
This commit is contained in:
robojerk
parent
5e8730df43
commit
aaf662d5b1
87 changed files with 1334 additions and 570 deletions
230
README.md
230
README.md
|
|
@ -1 +1,229 @@
|
|||
# deb-bootupd\n\nDebian package for bootupd
|
||||
# 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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue