Particle-OS System Tools

A comprehensive collection of tools for creating and managing immutable Ubuntu systems, inspired by uBlue OS but designed specifically for Particle-OS - a Ubuntu-based immutable distribution. These tools provide functionality similar to Fedora Silverblue/Kinoite but are built for Ubuntu/Debian-based distributions.

🎯 Overview

Particle-OS 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

Important: While these tools are inspired by uBlue OS concepts and design patterns, they are specifically designed for Particle-OS - a Ubuntu-based immutable system. The tools are optimized for Ubuntu/Debian package management (apt/dpkg) rather than RPM-based systems.

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Particle-OS System                       │
├─────────────────────────────────────────────────────────────┤
│  orchestrator.sh (System 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    • particle-config.sh              │
│  • bootc-alternative.sh  • particle-logrotate.sh           │
│  • dracut-module.sh      • install-particle-os.sh          │
│  • fsverity-utils        • Integrity verification          │
└─────────────────────────────────────────────────────────────┘

🚀 Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd tools

# Run the installation script
sudo ./install-particle-os.sh

# Verify installation
sudo ./test-integration.sh

Basic Usage

# Install packages and create new system image
sudo ./orchestrator.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 ./orchestrator.sh rebase ubuntu-base-25.04

# Rollback to previous deployment
sudo ./orchestrator.sh rollback

# Check system status
sudo ./orchestrator.sh status

📦 Core Components

1. orchestrator.sh - System Orchestrator

The central orchestrator that coordinates all Particle-OS 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:

sudo ./orchestrator.sh install <base-image> <package1> [package2]...
sudo ./orchestrator.sh rebase <new-base-image>
sudo ./orchestrator.sh rollback [target-image]
sudo ./orchestrator.sh status

2. apt-layer.sh - Package Layer Management

Advanced package management with layer-based approach, designed for Ubuntu/Debian systems:

• 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
• Ubuntu/Debian Optimized: Uses apt/dpkg instead of RPM

Usage:

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

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

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

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

# 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

particle-config.sh

Unified configuration system for Particle-OS:

# Show configuration
sudo ./particle-config.sh show

# Update configuration
sudo ./particle-config.sh update

# Validate configuration
sudo ./particle-config.sh validate

particle-logrotate.sh

Log rotation and maintenance for Particle-OS:

# Rotate oversized logs
sudo ./particle-logrotate.sh rotate

# Clean up old logs
sudo ./particle-logrotate.sh cleanup

# Show log statistics
sudo ./particle-logrotate.sh stats

🧪 Testing

Comprehensive test suite for all Particle-OS components:

# 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

# 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/: Complete apt-layer.sh documentation
• composefs/: ComposeFS alternative documentation
• bootupd/: Bootloader management documentation
• 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)
orchestrator.sh	✅ Production Ready	System orchestrator with transaction management
oci-integration.sh	✅ Production Ready	Container image export/import
particle-config.sh	✅ Production Ready	Unified configuration system
particle-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

# Clone repository
git clone <repository-url>
cd tools

# Install development dependencies
sudo ./install-particle-os.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. While inspired by uBlue OS concepts, these tools are specifically optimized for Particle-OS - a Ubuntu-based immutable distribution.