robojerk
ae7c1f6e4b
- Moved src/apt-layer/temp to archive/ - Moved src/bootupd/temp to archive/bootupd-temp - Moved src/composefs/temp to archive/composefs-temp - Cleaned up source directories to remove empty temp folders
343 lines
No EOL
12 KiB
Markdown
343 lines
No EOL
12 KiB
Markdown
# Ubuntu uBlue System Tools
|
|
|
|
A comprehensive collection of tools for creating and managing immutable Ubuntu systems, providing functionality similar to Fedora Silverblue/Kinoite but designed specifically for Ubuntu/Debian-based distributions.
|
|
|
|
## 🎯 Overview
|
|
|
|
Ubuntu uBlue System Tools provides a complete solution for immutable Ubuntu systems using:
|
|
- **ComposeFS Alternative**: Immutable filesystem backend using squashfs and overlayfs
|
|
- **apt-layer**: Package management and layer creation (similar to rpm-ostree)
|
|
- **bootupd Alternative**: Bootloader management and deployment
|
|
- **Live Overlay System**: Temporary package installation without rebooting
|
|
- **OCI Integration**: Container image export/import capabilities
|
|
- **Transaction Management**: Atomic operations with rollback support
|
|
|
|
## 🏗️ System Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Ubuntu uBlue System │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ main.sh (Orchestrator) │
|
|
│ ┌─────────────┬─────────────┬─────────────┐ │
|
|
│ │ apt-layer.sh│composefs-alt│bootupd-alt │ │
|
|
│ │ │ │ │ │
|
|
│ │ • Package │ • Immutable │ • Bootloader│ │
|
|
│ │ layers │ filesystem│ management│ │
|
|
│ │ • Live │ • SquashFS │ • UEFI/GRUB │ │
|
|
│ │ overlay │ • OverlayFS │ • Deployment│ │
|
|
│ └─────────────┴─────────────┴─────────────┘ │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ Supporting Tools │
|
|
│ • oci-integration.sh • ublue-config.sh │
|
|
│ • bootc-alternative.sh • ublue-logrotate.sh │
|
|
│ • dracut-module.sh • install-ubuntu-ublue.sh │
|
|
│ • fsverity-utils • Integrity verification │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd tools
|
|
|
|
# Run the installation script
|
|
sudo ./install-ubuntu-ublue.sh
|
|
|
|
# Verify installation
|
|
sudo ./test-integration.sh
|
|
```
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Install packages and create new system image
|
|
sudo ./main.sh install ubuntu-base-24.04 firefox steam
|
|
|
|
# Install packages on live system (no reboot required)
|
|
sudo ./apt-layer.sh --live-install firefox steam
|
|
|
|
# Commit live changes to permanent layer
|
|
sudo ./apt-layer.sh --live-commit "Add gaming packages"
|
|
|
|
# Rebase to new Ubuntu version
|
|
sudo ./main.sh rebase ubuntu-base-25.04
|
|
|
|
# Rollback to previous deployment
|
|
sudo ./main.sh rollback
|
|
|
|
# Check system status
|
|
sudo ./main.sh status
|
|
```
|
|
|
|
## 📦 Core Components
|
|
|
|
### 1. **main.sh** - System Orchestrator
|
|
The central orchestrator that coordinates all uBlue operations:
|
|
- **Package Installation**: Atomic package installation with new image creation
|
|
- **System Rebase**: Upgrade to new base images while preserving layers
|
|
- **Rollback Management**: Safe rollback to previous deployments
|
|
- **Transaction Management**: Atomic operations with automatic rollback
|
|
|
|
**Usage:**
|
|
```bash
|
|
sudo ./main.sh install <base-image> <package1> [package2]...
|
|
sudo ./main.sh rebase <new-base-image>
|
|
sudo ./main.sh rollback [target-image]
|
|
sudo ./main.sh status
|
|
```
|
|
|
|
### 2. **apt-layer.sh** - Package Layer Management
|
|
Advanced package management with layer-based approach:
|
|
- **Layer Creation**: Create new system layers with packages
|
|
- **Live Overlay**: Install packages without rebooting
|
|
- **Container Support**: Build layers in containers for isolation
|
|
- **Transaction Safety**: Atomic layer operations with rollback
|
|
- **OCI Integration**: Export/import layers as container images
|
|
|
|
**Usage:**
|
|
```bash
|
|
# Create new layer (traditional chroot-based)
|
|
sudo ./apt-layer.sh ubuntu-base/24.04 gaming/24.04 steam wine
|
|
|
|
# Create layer with container isolation
|
|
sudo ./apt-layer.sh --container ubuntu-base/24.04 dev/24.04 vscode git
|
|
|
|
# Live package installation (no reboot required)
|
|
sudo ./apt-layer.sh --live-install firefox
|
|
|
|
# Commit live changes to permanent layer
|
|
sudo ./apt-layer.sh --live-commit "Add browser"
|
|
|
|
# Export layer as OCI container image
|
|
sudo ./apt-layer.sh --oci-export gaming/24.04 my-registry/gaming:latest
|
|
|
|
# List all layers
|
|
sudo ./apt-layer.sh --list
|
|
|
|
# Rollback to previous layer
|
|
sudo ./apt-layer.sh --rollback gaming/24.04
|
|
```
|
|
|
|
### 3. **composefs-alternative.sh** - Immutable Filesystem
|
|
Provides immutable filesystem functionality using squashfs and overlayfs:
|
|
- **Image Creation**: Create compressed system images
|
|
- **Layer Management**: Manage multiple filesystem layers
|
|
- **Mount Management**: Mount/unmount images with overlay support
|
|
- **Content Verification**: Hash-based content verification
|
|
|
|
**Usage:**
|
|
```bash
|
|
# Create image from directory
|
|
sudo ./composefs-alternative.sh create my-image /path/to/rootfs
|
|
|
|
# Mount image
|
|
sudo ./composefs-alternative.sh mount my-image /mnt/point
|
|
|
|
# List images
|
|
sudo ./composefs-alternative.sh list-images
|
|
|
|
# Remove image
|
|
sudo ./composefs-alternative.sh remove my-image
|
|
```
|
|
|
|
### 4. **bootupd-alternative.sh** - Bootloader Management
|
|
Manages bootloader configuration and deployment:
|
|
- **UEFI Support**: Full UEFI bootloader management
|
|
- **GRUB Integration**: GRUB configuration and updates
|
|
- **Deployment**: Deploy new images as bootable entries
|
|
- **Rollback**: Safe bootloader rollback capabilities
|
|
- **Multi-bootloader Support**: UEFI, GRUB, LILO, syslinux
|
|
|
|
**Usage:**
|
|
```bash
|
|
# Set default boot entry
|
|
sudo ./bootupd-alternative.sh set-default my-image
|
|
|
|
# List boot entries
|
|
sudo ./bootupd-alternative.sh list-entries
|
|
|
|
# Check status
|
|
sudo ./bootupd-alternative.sh status
|
|
|
|
# Rollback bootloader
|
|
sudo ./bootupd-alternative.sh rollback
|
|
|
|
# Register new image with bootloader
|
|
sudo ./bootupd-alternative.sh register my-image
|
|
```
|
|
|
|
## 🔧 Supporting Tools
|
|
|
|
### **oci-integration.sh**
|
|
OCI container image export/import for ComposeFS images:
|
|
```bash
|
|
# Export layer as OCI image
|
|
sudo ./oci-integration.sh export my-layer my-registry/my-image:latest
|
|
|
|
# Import OCI image as layer
|
|
sudo ./oci-integration.sh import my-registry/my-image:latest my-layer
|
|
|
|
# List available OCI images
|
|
sudo ./oci-integration.sh list
|
|
```
|
|
|
|
### **bootc-alternative.sh**
|
|
Container-native bootable image system:
|
|
```bash
|
|
# Create bootable container image
|
|
sudo ./bootc-alternative.sh create ubuntu:24.04 my-bootable-image
|
|
|
|
# Deploy container as bootable system
|
|
sudo ./bootc-alternative.sh deploy my-bootable-image
|
|
|
|
# Update to new container image
|
|
sudo ./bootc-alternative.sh update my-container:v2.0
|
|
|
|
# Rollback to previous image
|
|
sudo ./bootc-alternative.sh rollback
|
|
```
|
|
|
|
### **ublue-config.sh**
|
|
Unified configuration system:
|
|
```bash
|
|
# Show configuration
|
|
sudo ./ublue-config.sh show
|
|
|
|
# Update configuration
|
|
sudo ./ublue-config.sh update
|
|
|
|
# Validate configuration
|
|
sudo ./ublue-config.sh validate
|
|
```
|
|
|
|
### **ublue-logrotate.sh**
|
|
Log rotation and maintenance:
|
|
```bash
|
|
# Rotate oversized logs
|
|
sudo ./ublue-logrotate.sh rotate
|
|
|
|
# Clean up old logs
|
|
sudo ./ublue-logrotate.sh cleanup
|
|
|
|
# Show log statistics
|
|
sudo ./ublue-logrotate.sh stats
|
|
```
|
|
|
|
## 🧪 Testing
|
|
|
|
Comprehensive test suite for all components:
|
|
|
|
```bash
|
|
# Run full integration tests
|
|
sudo ./test-integration.sh
|
|
|
|
# Test specific components
|
|
sudo ./test-apt-layer.sh
|
|
sudo ./test-composefs-integration.sh
|
|
```
|
|
|
|
## 📋 Requirements
|
|
|
|
### System Requirements
|
|
- **OS**: Ubuntu 22.04+ / Debian 12+ / Pop!_OS 22.04+
|
|
- **Architecture**: x86_64, ARM64
|
|
- **Boot**: UEFI or Legacy BIOS
|
|
- **Storage**: 20GB+ free space
|
|
- **Memory**: 4GB+ RAM
|
|
|
|
### Dependencies
|
|
```bash
|
|
# Core dependencies
|
|
sudo apt install squashfs-tools jq rsync mount losetup
|
|
|
|
# Bootloader dependencies
|
|
sudo apt install grub-efi-amd64 efibootmgr
|
|
|
|
# File integrity verification
|
|
sudo apt install fsverity-utils
|
|
|
|
# Container dependencies (optional)
|
|
sudo apt install podman docker.io
|
|
```
|
|
|
|
## 🔒 Security Features
|
|
|
|
- **Immutable Design**: System images cannot be modified at runtime
|
|
- **Content Verification**: SHA256 hash verification of all content
|
|
- **Transaction Safety**: Atomic operations with automatic rollback
|
|
- **Isolation**: Container-based layer building for security
|
|
- **Audit Logging**: Comprehensive logging of all operations
|
|
- **Command Injection Protection**: Safe command execution without eval
|
|
- **Resource Cleanup**: Automatic cleanup of temporary files and mounts
|
|
- **Path Validation**: Input sanitization and path traversal protection
|
|
|
|
## 📚 Documentation
|
|
|
|
Detailed documentation is available in the `docs/` directory:
|
|
|
|
- **[apt-layer/](docs/apt-layer/)**: Complete apt-layer.sh documentation
|
|
- **[composefs/](docs/composefs/)**: ComposeFS alternative documentation
|
|
- **[bootupd/](docs/bootupd/)**: Bootloader management documentation
|
|
- **[bootc/](docs/bootc/)**: Container-native booting documentation
|
|
|
|
## 🚧 Development Status
|
|
|
|
| Component | Status | Notes |
|
|
|-----------|--------|-------|
|
|
| apt-layer.sh | ✅ Production Ready | Full layer management with live overlay, OCI integration |
|
|
| composefs-alternative.sh | ✅ Production Ready | Immutable filesystem backend with squashfs/overlayfs |
|
|
| bootupd-alternative.sh | ✅ Production Ready | Multi-bootloader support (UEFI, GRUB, LILO, syslinux) |
|
|
| main.sh | ✅ Production Ready | System orchestrator with transaction management |
|
|
| oci-integration.sh | ✅ Production Ready | Container image export/import |
|
|
| ublue-config.sh | ✅ Production Ready | Unified configuration system |
|
|
| ublue-logrotate.sh | ✅ Production Ready | Log rotation and maintenance |
|
|
| bootc-alternative.sh | 🔄 In Development | Container-native booting |
|
|
|
|
## 🤝 Contributing
|
|
|
|
This project welcomes contributions! Please see the individual component documentation for development guidelines.
|
|
|
|
### Development Setup
|
|
```bash
|
|
# Clone repository
|
|
git clone <repository-url>
|
|
cd tools
|
|
|
|
# Install development dependencies
|
|
sudo ./install-ubuntu-ublue.sh --dev
|
|
|
|
# Run tests
|
|
sudo ./test-integration.sh
|
|
|
|
# Run component-specific tests
|
|
sudo ./test-apt-layer.sh
|
|
sudo ./test-composefs-integration.sh
|
|
```
|
|
|
|
### Development Guidelines
|
|
- Follow the existing code style and patterns
|
|
- Add comprehensive error handling and logging
|
|
- Include tests for new features
|
|
- Update documentation for any API changes
|
|
- Ensure all operations are atomic with rollback support
|
|
|
|
## 📄 License
|
|
|
|
This project is open source. Please check individual component licenses.
|
|
|
|
## 🆘 Support
|
|
|
|
- **Issues**: Report bugs and feature requests via GitHub issues
|
|
- **Documentation**: Check the `docs/` directory for detailed guides
|
|
- **Testing**: Run `./test-integration.sh` for system diagnostics
|
|
- **Troubleshooting**: Check component-specific troubleshooting guides in `docs/`
|
|
- **Security**: Review security analysis in `docs/apt-layer/AGGRESSIVE-SCRUTINY-RESPONSE.md`
|
|
|
|
---
|
|
|
|
**Note**: All tools are designed to work 1:1 with their official counterparts and are compatible with Ubuntu, Debian, and Pop!_OS systems. |