apt-ostree/.notes/cli/rpm-ostree.md

rpm-ostree CLI Analysis

Executive Summary

rpm-ostree provides a comprehensive command-line interface that serves as the primary user interface for the hybrid image/package system. The CLI is designed to be intuitive, powerful, and consistent, offering both basic operations for end users and advanced features for system administrators.

CLI Architecture

Command Structure

rpm-ostree follows a hierarchical command structure with main commands and subcommands:

rpm-ostree [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGUMENTS]

Global Options

• --version: Show version information
• --help: Show help information
• --verbose: Enable verbose output
• --quiet: Suppress output
• --json: Output in JSON format
• --sysroot=PATH: Specify system root path

Core Commands

1. Status Command

Purpose: Display system status and deployment information

Usage:

rpm-ostree status [OPTIONS]

Options:

• --json: Output in JSON format
• --booted: Show only booted deployment
• --pending: Show only pending deployment

Output Format:

State: idle
Deployments:
* ostree://fedora:fedora/x86_64/silverblue
                   Version: 38.20231201.0 (2023-12-01 12:34:56)
                BaseCommit: abc123def456...
              GPGSignature: Valid signature by 1234567890ABCDEF
           LayeredPackages: vim git

  ostree://fedora:fedora/x86_64/silverblue
                   Version: 38.20231115.0 (2023-11-15 10:20:30)
                BaseCommit: def456ghi789...
              GPGSignature: Valid signature by 1234567890ABCDEF
           LayeredPackages: vim

Implementation:

• Queries OSTree sysroot for deployment information
• Displays current and available deployments
• Shows layered packages and version information
• Indicates booted and pending deployments

2. Upgrade Command

Purpose: Upgrade system to latest version

Usage:

rpm-ostree upgrade [OPTIONS]

Options:

• --check: Check for updates without upgrading
• --download-only: Download updates without installing
• --reboot: Automatically reboot after upgrade
• --allow-downgrade: Allow downgrading packages
• --unchanged-exit-77: Exit with 77 if no changes

Execution Flow:

1. Check for available updates
2. Download new packages
3. Create new deployment
4. Install updates
5. Update boot configuration
6. Optionally reboot

Implementation:

• Uses libdnf to check for updates
• Downloads packages via DNF
• Creates new OSTree commit with updates
• Manages deployment switching
• Handles rollback on failure

3. Rollback Command

Purpose: Rollback to previous deployment

Usage:

rpm-ostree rollback [OPTIONS]

Options:

• --reboot: Automatically reboot after rollback
• --not-as-default: Don't set as default boot option

Execution Flow:

1. Identify previous deployment
2. Switch to previous deployment
3. Update boot configuration
4. Optionally reboot

Implementation:

• Queries OSTree for available deployments
• Switches to previous deployment
• Updates GRUB/systemd-boot configuration
• Manages boot order

4. Deploy Command

Purpose: Deploy specific version or commit

Usage:

rpm-ostree deploy [OPTIONS] [REF]

Options:

• --reboot: Automatically reboot after deployment
• --not-as-default: Don't set as default boot option
• --os=OSNAME: Specify operating system name

Examples:

# Deploy specific version
rpm-ostree deploy fedora:fedora/x86_64/silverblue/38.20231201.0

# Deploy specific commit
rpm-ostree deploy abc123def456...

# Deploy with reboot
rpm-ostree deploy --reboot fedora:fedora/x86_64/silverblue/38.20231201.0

Implementation:

• Validates deployment reference
• Downloads deployment if needed
• Switches to specified deployment
• Updates boot configuration

5. Install Command

Purpose: Install packages as layers

Usage:

rpm-ostree install [OPTIONS] PACKAGES...

Options:

• --reboot: Automatically reboot after installation
• --allow-inactive: Allow installing on inactive deployment
• --idempotent: Don't error if packages already installed

Examples:

# Install single package
rpm-ostree install vim

# Install multiple packages
rpm-ostree install vim git build-essential

# Install with reboot
rpm-ostree install --reboot firefox

Execution Flow:

1. Resolve package dependencies
2. Download packages
3. Create new deployment with packages
4. Install packages in new deployment
5. Update boot configuration
6. Optionally reboot

Implementation:

• Uses libdnf for dependency resolution
• Downloads packages via DNF
• Creates new OSTree commit with packages
• Manages package layering
• Handles conflicts and rollback

6. Uninstall Command

Purpose: Remove layered packages

Usage:

rpm-ostree uninstall [OPTIONS] PACKAGES...

Options:

• --reboot: Automatically reboot after uninstallation
• --idempotent: Don't error if packages not installed

Examples:

# Remove single package
rpm-ostree uninstall vim

# Remove multiple packages
rpm-ostree uninstall vim git

# Remove with reboot
rpm-ostree uninstall --reboot firefox

Execution Flow:

1. Check if packages are installed
2. Create new deployment without packages
3. Remove packages from new deployment
4. Update boot configuration
5. Optionally reboot

Implementation:

• Validates package installation status
• Creates new deployment without packages
• Manages package removal
• Handles dependencies and conflicts

7. Override Command

Purpose: Manage package overrides

Usage:

rpm-ostree override [SUBCOMMAND] [OPTIONS] [ARGUMENTS]

Subcommands:

• replace: Replace package with different version
• remove: Remove package from base
• reset: Reset package to base version
• list: List current overrides

Examples:

# Replace package
rpm-ostree override replace kernel /path/to/custom-kernel.rpm

# Remove package from base
rpm-ostree override remove package-name

# Reset package
rpm-ostree override reset package-name

# List overrides
rpm-ostree override list

Implementation:

• Manages package override state
• Handles package replacement
• Tracks override history
• Manages base package modifications

8. Rebase Command

Purpose: Switch to different base image

Usage:

rpm-ostree rebase [OPTIONS] [REF]

Options:

• --reboot: Automatically reboot after rebase
• --os=OSNAME: Specify operating system name

Examples:

# Rebase to different version
rpm-ostree rebase fedora:fedora/x86_64/silverblue/39

# Rebase to different OS
rpm-ostree rebase --os=fedora fedora:fedora/x86_64/silverblue/39

Execution Flow:

1. Download new base image
2. Merge user packages to new base
3. Create new deployment
4. Update boot configuration
5. Optionally reboot

Implementation:

• Downloads new base image
• Preserves user packages
• Creates new deployment
• Manages package compatibility

9. Compose Command

Purpose: Build custom images

Usage:

rpm-ostree compose [SUBCOMMAND] [OPTIONS] [ARGUMENTS]

Subcommands:

• tree: Build tree from configuration
• build-image: Build container image
• extensions: Manage extensions

Examples:

# Build tree
rpm-ostree compose tree config.yaml

# Build container image
rpm-ostree compose build-image --format=docker output.tar

# Manage extensions
rpm-ostree compose extensions list

Implementation:

• Parses configuration files
• Builds custom images
• Manages extensions
• Generates container images

10. DB Command

Purpose: Query package database

Usage:

rpm-ostree db [SUBCOMMAND] [OPTIONS] [ARGUMENTS]

Subcommands:

• diff: Show differences between deployments
• list: List packages in deployment
• version: Show package versions

Examples:

# Show differences
rpm-ostree db diff deployment1 deployment2

# List packages
rpm-ostree db list

# Show versions
rpm-ostree db version package-name

Implementation:

• Queries package database
• Compares deployments
• Lists package information
• Shows version details

11. Search Command

Purpose: Search for packages

Usage:

rpm-ostree search [OPTIONS] QUERY

Options:

• --json: Output in JSON format
• --limit=N: Limit number of results

Examples:

# Search by name
rpm-ostree search firefox

# Search by description
rpm-ostree search "web browser"

Implementation:

• Uses libdnf for package search
• Searches package metadata
• Returns relevant results
• Supports various search criteria

12. Kargs Command

Purpose: Manage kernel arguments

Usage:

rpm-ostree kargs [OPTIONS] [ARGUMENTS]

Options:

• --reboot: Automatically reboot after changes
• --append: Append kernel arguments
• --delete: Delete kernel arguments
• --replace: Replace kernel arguments

Examples:

# Show current kernel arguments
rpm-ostree kargs

# Append kernel argument
rpm-ostree kargs --append="quiet"

# Delete kernel argument
rpm-ostree kargs --delete="quiet"

# Replace kernel arguments
rpm-ostree kargs --replace="quiet splash"

Implementation:

• Manages kernel argument state
• Updates boot configuration
• Handles argument modification
• Preserves argument history

13. Initramfs Command

Purpose: Manage initramfs

Usage:

rpm-ostree initramfs [SUBCOMMAND] [OPTIONS] [ARGUMENTS]

Subcommands:

• enable: Enable initramfs
• disable: Disable initramfs
• etc: Manage initramfs files

Examples:

# Enable initramfs
rpm-ostree initramfs enable

# Disable initramfs
rpm-ostree initramfs disable

# Manage files
rpm-ostree initramfs etc --track=/etc/fstab

Implementation:

• Manages initramfs state
• Handles initramfs generation
• Tracks initramfs files
• Updates boot configuration

14. Usroverlay Command

Purpose: Create transient overlayfs to /usr

Usage:

rpm-ostree usroverlay [OPTIONS] [COMMAND]

Options:

• --init: Initialize overlay
• --cleanup: Clean up overlay

Examples:

# Initialize overlay
rpm-ostree usroverlay --init

# Run command in overlay
rpm-ostree usroverlay --init -- dnf install package

# Clean up overlay
rpm-ostree usroverlay --cleanup

Implementation:

• Creates overlayfs mount
• Manages overlay state
• Handles command execution
• Cleans up overlay

15. Apply-Live Command

Purpose: Apply changes to running system

Usage:

rpm-ostree apply-live [OPTIONS]

Options:

• --reload: Reload configuration
• --replace: Replace running system

Examples:

# Apply live changes
rpm-ostree apply-live

# Apply with reload
rpm-ostree apply-live --reload

Implementation:

• Applies changes to running system
• Manages live updates
• Handles configuration reload
• Manages system state

16. Cancel Command

Purpose: Cancel pending transaction

Usage:

rpm-ostree cancel [OPTIONS]

Options:

• --force: Force cancellation

Examples:

# Cancel transaction
rpm-ostree cancel

# Force cancellation
rpm-ostree cancel --force

Implementation:

• Cancels pending transactions
• Cleans up transaction state
• Handles force cancellation
• Manages rollback

17. Cleanup Command

Purpose: Clean up old deployments

Usage:

rpm-ostree cleanup [OPTIONS]

Options:

• --base: Clean up base images
• --repomd: Clean up repository metadata
• --rollback: Clean up rollback deployments

Examples:

# Clean up old deployments
rpm-ostree cleanup

# Clean up base images
rpm-ostree cleanup --base

# Clean up rollback deployments
rpm-ostree cleanup --rollback

Implementation:

• Identifies old deployments
• Removes unused deployments
• Cleans up base images
• Manages disk space

18. Reload Command

Purpose: Reload configuration

Usage:

rpm-ostree reload [OPTIONS]

Options:

• --os=OSNAME: Specify operating system name

Examples:

# Reload configuration
rpm-ostree reload

# Reload specific OS
rpm-ostree reload --os=fedora

Implementation:

• Reloads system configuration
• Updates repository metadata
• Refreshes package information
• Manages configuration state

19. Reset Command

Purpose: Reset system state

Usage:

rpm-ostree reset [OPTIONS]

Options:

• --os=OSNAME: Specify operating system name
• --hard: Hard reset (remove all changes)

Examples:

# Reset system
rpm-ostree reset

# Hard reset
rpm-ostree reset --hard

Implementation:

• Resets system state
• Removes user changes
• Restores base state
• Manages state reset

20. Refresh-MD Command

Purpose: Refresh repository metadata

Usage:

rpm-ostree refresh-md [OPTIONS]

Options:

• --os=OSNAME: Specify operating system name

Examples:

# Refresh metadata
rpm-ostree refresh-md

# Refresh specific OS
rpm-ostree refresh-md --os=fedora

Implementation:

• Downloads repository metadata
• Updates package information
• Refreshes repository state
• Manages metadata cache

Advanced Features

JSON Output

Many commands support JSON output for programmatic use:

# JSON status output
rpm-ostree status --json

# JSON search output
rpm-ostree search --json firefox

Verbose Output

Enable detailed output for debugging:

# Verbose upgrade
rpm-ostree upgrade --verbose

# Verbose install
rpm-ostree install --verbose vim

Dry Run Mode

Some commands support dry run mode for testing:

# Dry run upgrade
rpm-ostree upgrade --check

# Dry run install
rpm-ostree install --dry-run vim

Error Handling

Common Error Scenarios

1. Network Errors: Package download failures
2. Dependency Conflicts: Package dependency issues
3. Disk Space: Insufficient storage space
4. Permission Errors: Insufficient privileges
5. OSTree Errors: Filesystem operation failures

Error Recovery

• Automatic Rollback: Failed operations automatically rollback
• Manual Recovery: Manual recovery procedures available
• Error Reporting: Detailed error messages and guidance
• Logging: Comprehensive logging for debugging

Integration with Other Tools

GUI Integration

• GNOME Software: Integration with GNOME Software Center
• KDE Discover: Integration with KDE Discover
• Flatpak: Integration with Flatpak applications

System Integration

• systemd: Integration with systemd services
• D-Bus: D-Bus interface for other applications
• PolicyKit: Authentication and authorization

Performance Considerations

Optimization Strategies

1. Parallel Downloads: Concurrent package downloads
2. Caching: Package and metadata caching
3. Delta Updates: Incremental update support
4. Compression: Efficient data compression

Resource Usage

• Memory: Efficient memory usage for large operations
• Disk: Optimized disk usage through deduplication
• Network: Bandwidth optimization for downloads
• CPU: Parallel processing for package operations

Security Features

Package Verification

• GPG Signatures: Package signature verification
• Checksums: Package integrity checks
• Secure Downloads: HTTPS for package downloads

Access Control

• PolicyKit: Privileged operation authentication
• User Permissions: User-specific permissions
• System Policies: System-wide security policies

Future Enhancements

Planned Features

1. Container Integration: Direct container support
2. Cloud Integration: Cloud deployment support
3. Advanced Search: Enhanced search capabilities
4. Performance Monitoring: Built-in performance monitoring

CLI Improvements

1. Interactive Mode: Interactive command mode
2. Command Completion: Enhanced command completion
3. Progress Indicators: Better progress reporting
4. Configuration Management: Enhanced configuration options