robojerk
d295f9bb4d
- ✅ Real package installation (replaced mock installation) - ✅ Real OSTree commit creation from installed packages - ✅ OCI image creation from both commits and rootfs - ✅ Full bootc compatibility with proper labels - ✅ Comprehensive test suite (test-bootc-apt-ostree.sh) - ✅ Container tool validation (skopeo, podman) - ✅ Updated compatibility reports for Ubuntu Questing - ✅ Fixed OCI schema version and field naming issues - ✅ Temporary directory lifecycle fixes - ✅ Serde rename attributes for OCI JSON compliance Ready for Aurora-style workflow deployment!
776 lines
No EOL
16 KiB
Markdown
776 lines
No EOL
16 KiB
Markdown
# 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**:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree uninstall [OPTIONS] PACKAGES...
|
|
```
|
|
|
|
**Options**:
|
|
- `--reboot`: Automatically reboot after uninstallation
|
|
- `--idempotent`: Don't error if packages not installed
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree rebase [OPTIONS] [REF]
|
|
```
|
|
|
|
**Options**:
|
|
- `--reboot`: Automatically reboot after rebase
|
|
- `--os=OSNAME`: Specify operating system name
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree compose [SUBCOMMAND] [OPTIONS] [ARGUMENTS]
|
|
```
|
|
|
|
**Subcommands**:
|
|
- `tree`: Build tree from configuration
|
|
- `build-image`: Build container image
|
|
- `extensions`: Manage extensions
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree db [SUBCOMMAND] [OPTIONS] [ARGUMENTS]
|
|
```
|
|
|
|
**Subcommands**:
|
|
- `diff`: Show differences between deployments
|
|
- `list`: List packages in deployment
|
|
- `version`: Show package versions
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree search [OPTIONS] QUERY
|
|
```
|
|
|
|
**Options**:
|
|
- `--json`: Output in JSON format
|
|
- `--limit=N`: Limit number of results
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree kargs [OPTIONS] [ARGUMENTS]
|
|
```
|
|
|
|
**Options**:
|
|
- `--reboot`: Automatically reboot after changes
|
|
- `--append`: Append kernel arguments
|
|
- `--delete`: Delete kernel arguments
|
|
- `--replace`: Replace kernel arguments
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree initramfs [SUBCOMMAND] [OPTIONS] [ARGUMENTS]
|
|
```
|
|
|
|
**Subcommands**:
|
|
- `enable`: Enable initramfs
|
|
- `disable`: Disable initramfs
|
|
- `etc`: Manage initramfs files
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree usroverlay [OPTIONS] [COMMAND]
|
|
```
|
|
|
|
**Options**:
|
|
- `--init`: Initialize overlay
|
|
- `--cleanup`: Clean up overlay
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree apply-live [OPTIONS]
|
|
```
|
|
|
|
**Options**:
|
|
- `--reload`: Reload configuration
|
|
- `--replace`: Replace running system
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree cancel [OPTIONS]
|
|
```
|
|
|
|
**Options**:
|
|
- `--force`: Force cancellation
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree cleanup [OPTIONS]
|
|
```
|
|
|
|
**Options**:
|
|
- `--base`: Clean up base images
|
|
- `--repomd`: Clean up repository metadata
|
|
- `--rollback`: Clean up rollback deployments
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree reload [OPTIONS]
|
|
```
|
|
|
|
**Options**:
|
|
- `--os=OSNAME`: Specify operating system name
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree reset [OPTIONS]
|
|
```
|
|
|
|
**Options**:
|
|
- `--os=OSNAME`: Specify operating system name
|
|
- `--hard`: Hard reset (remove all changes)
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
rpm-ostree refresh-md [OPTIONS]
|
|
```
|
|
|
|
**Options**:
|
|
- `--os=OSNAME`: Specify operating system name
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# JSON status output
|
|
rpm-ostree status --json
|
|
|
|
# JSON search output
|
|
rpm-ostree search --json firefox
|
|
```
|
|
|
|
### Verbose Output
|
|
|
|
Enable detailed output for debugging:
|
|
|
|
```bash
|
|
# Verbose upgrade
|
|
rpm-ostree upgrade --verbose
|
|
|
|
# Verbose install
|
|
rpm-ostree install --verbose vim
|
|
```
|
|
|
|
### Dry Run Mode
|
|
|
|
Some commands support dry run mode for testing:
|
|
|
|
```bash
|
|
# 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 |