particle-os-tools/docs/bootupd

bootloader-integration.sh Documentation

Overview

bootloader-integration.sh provides integration between Ubuntu uBlue layer management and bootloader configuration. It bridges the gap between ComposeFS images and boot entries, ensuring that new layers are properly registered and can be booted.

Script Description

The bootloader-integration.sh script enables:

• Boot Entry Registration: Register ComposeFS images with the bootloader
• Default Boot Setting: Set specific images as the default boot entry
• Boot Entry Management: Remove and list boot entries
• Initramfs Updates: Update initramfs for specific images
• Integration with apt-layer.sh: Automatic bootloader updates during layer operations

Key Features

• ComposeFS Integration: Works with ComposeFS images and their paths
• Bootupd Integration: Uses bootupd-alternative.sh for boot entry management
• Automatic Registration: Integrates with apt-layer.sh for seamless operation
• Kernel Version Detection: Automatically detects and uses appropriate kernel versions
• Initramfs Management: Updates initramfs for new images

Documentation Files

Core Documentation

• bootloader-integration-guide.md - Comprehensive user guide
• bootloader-integration-api.md - API reference and integration details

Technical Documentation

• bootloader-security.md - Security considerations and best practices
• bootloader-troubleshooting.md - Common issues and solutions

Quick Start

# Register a new image with the bootloader
bootloader-integration.sh register ubuntu-ublue/gaming/24.04

# Set an image as the default boot entry
bootloader-integration.sh set-default ubuntu-ublue/gaming/24.04

# List all boot entries
bootloader-integration.sh list

# Update initramfs for an image
bootloader-integration.sh update-initramfs ubuntu-ublue/gaming/24.04

Integration

bootloader-integration.sh integrates with:

• apt-layer.sh: Automatic bootloader updates during layer creation
• composefs-alternative.sh: For image path and status information
• bootupd-alternative.sh: For actual boot entry management
• ublue-config.sh: For unified configuration

Architecture

The script provides:

• Image Registration: Maps ComposeFS images to boot entries
• Boot Entry Management: Creates, updates, and removes boot entries
• Initramfs Updates: Ensures boot images have current initramfs
• Integration API: Clean interface for other scripts to use

Security Considerations

• Path Validation: Validates image paths before registration
• Kernel Version Verification: Ensures kernel version compatibility
• Privilege Requirements: Requires root privileges for bootloader operations
• Error Handling: Comprehensive error handling and rollback support

Development Status

The script is production-ready with:

• ✅ Secure command execution (no eval usage)
• ✅ Comprehensive error handling
• ✅ Integration with apt-layer.sh
• ✅ Boot entry management
• ✅ Initramfs update support

For more information, see the individual documentation files listed above.