robojerk
3dec23f8f7
- Fix trailing spaces and blank lines in Forgejo workflows - Update system requirements from Ubuntu Jammy/Bookworm to Debian 13+ (Trixie) - Update test treefile to use Debian Trixie instead of Ubuntu Jammy - Update documentation to reflect modern system requirements - Fix yamllint errors for CI/CD functionality - Ensure compatibility with modern OSTree and libapt versions
509 lines
13 KiB
Markdown
509 lines
13 KiB
Markdown
# Development Commands Usage Guide
|
|
|
|
## Overview
|
|
This document provides comprehensive usage examples for apt-ostree's development commands. These commands are hidden from normal help output and are intended for developers and system administrators debugging apt-ostree installations.
|
|
|
|
## Table of Contents
|
|
1. [testutils Commands](#testutils-commands)
|
|
2. [shlib-backend Commands](#shlib-backend-commands)
|
|
3. [internals Commands](#internals-commands)
|
|
4. [Common Use Cases](#common-use-cases)
|
|
5. [Troubleshooting](#troubleshooting)
|
|
|
|
## testutils Commands
|
|
|
|
### inject-pkglist
|
|
Inject a package list into an OSTree commit's metadata.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Inject a simple package list
|
|
sudo apt-ostree testutils inject-pkglist abc123 "apt,curl,nginx"
|
|
|
|
# Inject with specific commit and packages
|
|
sudo apt-ostree testutils inject-pkglist \
|
|
debian/13/amd64/commit/2025-01-15T10:30:00Z \
|
|
"apt,curl,nginx,postgresql-client"
|
|
```
|
|
|
|
#### Advanced Usage
|
|
```bash
|
|
# Inject from file
|
|
cat packages.txt | sudo apt-ostree testutils inject-pkglist abc123 -
|
|
|
|
# Inject with validation
|
|
sudo apt-ostree testutils inject-pkglist \
|
|
--validate-dependencies \
|
|
abc123 \
|
|
"apt,curl,nginx"
|
|
```
|
|
|
|
#### Use Cases
|
|
- **Testing package management**: Verify package list injection works correctly
|
|
- **Development workflows**: Test package metadata handling
|
|
- **Debugging**: Investigate package list issues in commits
|
|
|
|
### script-shell
|
|
Execute a script in a bubblewrap container with various options.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Execute a simple script
|
|
sudo apt-ostree testutils script-shell /tmp/test.sh
|
|
|
|
# Execute with arguments
|
|
sudo apt-ostree testutils script-shell /tmp/install.sh --install-package nginx
|
|
|
|
# Execute in read-only mode
|
|
sudo apt-ostree testutils script-shell /tmp/check.sh --read-only
|
|
```
|
|
|
|
#### Advanced Options
|
|
```bash
|
|
# Execute with custom root path
|
|
sudo apt-ostree testutils script-shell \
|
|
--rootpath /mnt/ostree/deploy/debian/13/amd64 \
|
|
/tmp/deploy-check.sh
|
|
|
|
# Execute as specific user/group
|
|
sudo apt-ostree testutils script-shell \
|
|
--user www-data \
|
|
--group www-data \
|
|
/tmp/web-test.sh
|
|
|
|
# Execute with custom working directory
|
|
sudo apt-ostree testutils script-shell \
|
|
--cwd /var/www \
|
|
/tmp/web-deploy.sh
|
|
|
|
# Execute with environment variables
|
|
sudo apt-ostree testutils script-shell \
|
|
--env "DEBUG=1" \
|
|
--env "TEST_MODE=1" \
|
|
/tmp/debug-test.sh
|
|
```
|
|
|
|
#### Use Cases
|
|
- **Testing deployments**: Verify scripts work in isolated environments
|
|
- **Debugging**: Test scripts without affecting the main system
|
|
- **Development**: Develop and test deployment scripts safely
|
|
|
|
### generate-synthetic-upgrade
|
|
Generate a synthetic upgrade for testing purposes.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Generate basic synthetic upgrade
|
|
sudo apt-ostree testutils generate-synthetic-upgrade
|
|
|
|
# Generate with specific parameters
|
|
sudo apt-ostree testutils generate-synthetic-upgrade \
|
|
--packages "apt,curl,nginx" \
|
|
--version-increment "patch"
|
|
```
|
|
|
|
#### Advanced Usage
|
|
```bash
|
|
# Generate upgrade with custom metadata
|
|
sudo apt-ostree testutils generate-synthetic-upgrade \
|
|
--metadata "test-mode=true" \
|
|
--metadata "generated-by=test-suite"
|
|
|
|
# Generate upgrade for specific architecture
|
|
sudo apt-ostree testutils generate-synthetic-upgrade \
|
|
--architecture amd64 \
|
|
--os-version "debian/13"
|
|
```
|
|
|
|
#### Use Cases
|
|
- **Testing upgrade paths**: Verify upgrade mechanisms work correctly
|
|
- **Development testing**: Test upgrade logic without real packages
|
|
- **CI/CD pipelines**: Generate test data for automated testing
|
|
|
|
### integration-read-only
|
|
Run integration tests in read-only mode.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Run basic integration tests
|
|
sudo apt-ostree testutils integration-read-only
|
|
|
|
# Run with specific test categories
|
|
sudo apt-ostree testutils integration-read-only \
|
|
--test-category "package-management" \
|
|
--test-category "system-operations"
|
|
```
|
|
|
|
#### Advanced Usage
|
|
```bash
|
|
# Run with custom test parameters
|
|
sudo apt-ostree testutils integration-read-only \
|
|
--test-timeout 300 \
|
|
--verbose-output \
|
|
--save-results /tmp/test-results.json
|
|
```
|
|
|
|
#### Use Cases
|
|
- **System validation**: Verify system state without making changes
|
|
- **Pre-deployment testing**: Test system before applying changes
|
|
- **Health checks**: Monitor system health and configuration
|
|
|
|
### c-units
|
|
Run C unit tests if available.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Run all available C unit tests
|
|
sudo apt-ostree testutils c-units
|
|
|
|
# Run specific test suite
|
|
sudo apt-ostree testutils c-units --suite "ostree-integration"
|
|
|
|
# Run with verbose output
|
|
sudo apt-ostree testutils c-units --verbose
|
|
```
|
|
|
|
#### Advanced Usage
|
|
```bash
|
|
# Run tests with custom compiler flags
|
|
sudo apt-ostree testutils c-units \
|
|
--cflags "-O2 -g" \
|
|
--ldflags "-L/usr/local/lib"
|
|
|
|
# Run tests in parallel
|
|
sudo apt-ostree testutils c-units --parallel --jobs 4
|
|
```
|
|
|
|
#### Use Cases
|
|
- **C library testing**: Test C library integrations
|
|
- **Performance testing**: Benchmark C-based operations
|
|
- **Compatibility testing**: Verify C library compatibility
|
|
|
|
### moo
|
|
Perform basic functionality tests.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Run basic functionality tests
|
|
sudo apt-ostree testutils moo
|
|
|
|
# Run specific test categories
|
|
sudo apt-ostree testutils moo --category "core-functions"
|
|
```
|
|
|
|
#### Use Cases
|
|
- **Quick health check**: Verify basic system functionality
|
|
- **Development testing**: Test during development cycles
|
|
- **Troubleshooting**: Identify basic system issues
|
|
|
|
## shlib-backend Commands
|
|
|
|
### get-basearch
|
|
Get the system's base architecture.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Get current system architecture
|
|
sudo apt-ostree shlib-backend get-basearch
|
|
|
|
# Get architecture for specific deployment
|
|
sudo apt-ostree shlib-backend get-basearch --deployment debian/13/amd64
|
|
```
|
|
|
|
#### Use Cases
|
|
- **Architecture detection**: Determine system architecture
|
|
- **Package selection**: Select appropriate packages for architecture
|
|
- **Deployment targeting**: Target deployments for specific architectures
|
|
|
|
### varsubst-basearch
|
|
Perform variable substitution for architecture-specific strings.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Substitute architecture variables
|
|
echo "arch={{arch}}" | sudo apt-ostree shlib-backend varsubst-basearch
|
|
|
|
# Substitute with custom source
|
|
sudo apt-ostree shlib-backend varsubst-basearch \
|
|
"Package-{{arch}}-{{os}}-{{version}}.deb"
|
|
```
|
|
|
|
#### Advanced Usage
|
|
```bash
|
|
# Substitute multiple variables
|
|
sudo apt-ostree shlib-backend varsubst-basearch \
|
|
"{{os}}-{{arch}}-{{version}}-{{flavor}}"
|
|
|
|
# Substitute with custom values
|
|
sudo apt-ostree shlib-backend varsubst-basearch \
|
|
--custom-vars "os=debian,version=13,flavor=minimal" \
|
|
"{{os}}-{{arch}}-{{version}}-{{flavor}}"
|
|
```
|
|
|
|
#### Use Cases
|
|
- **Template processing**: Process configuration templates
|
|
- **Package naming**: Generate architecture-specific package names
|
|
- **Deployment scripts**: Create architecture-aware deployment scripts
|
|
|
|
### packagelist-from-commit
|
|
Extract package list from an OSTree commit.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Extract package list from commit
|
|
sudo apt-ostree shlib-backend packagelist-from-commit abc123
|
|
|
|
# Extract with specific format
|
|
sudo apt-ostree shlib-backend packagelist-from-commit \
|
|
--format json \
|
|
abc123
|
|
```
|
|
|
|
#### Advanced Usage
|
|
```bash
|
|
# Extract with metadata
|
|
sudo apt-ostree shlib-backend packagelist-from-commit \
|
|
--include-metadata \
|
|
--metadata-keys "apt.packages,apt.dependencies" \
|
|
abc123
|
|
|
|
# Extract to file
|
|
sudo apt-ostree shlib-backend packagelist-from-commit \
|
|
--output /tmp/packages.txt \
|
|
abc123
|
|
```
|
|
|
|
#### Use Cases
|
|
- **Package analysis**: Analyze packages in specific commits
|
|
- **Dependency tracking**: Track package dependencies across commits
|
|
- **Audit trails**: Create audit trails of package changes
|
|
|
|
## internals Commands
|
|
|
|
### diagnostics
|
|
Run comprehensive system diagnostics.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Run all diagnostics
|
|
sudo apt-ostree internals diagnostics
|
|
|
|
# Run specific diagnostic categories
|
|
sudo apt-ostree internals diagnostics \
|
|
--category "ostree" \
|
|
--category "apt" \
|
|
--category "daemon"
|
|
```
|
|
|
|
#### Advanced Usage
|
|
```bash
|
|
# Run with custom parameters
|
|
sudo apt-ostree internals diagnostics \
|
|
--timeout 600 \
|
|
--output-format json \
|
|
--save-report /tmp/diagnostics.json
|
|
|
|
# Run with specific checks
|
|
sudo apt-ostree internals diagnostics \
|
|
--checks "repository-integrity,package-database,daemon-status"
|
|
```
|
|
|
|
#### Use Cases
|
|
- **System health check**: Comprehensive system health assessment
|
|
- **Problem diagnosis**: Identify system issues and misconfigurations
|
|
- **Pre-maintenance**: Verify system state before maintenance
|
|
|
|
### validate-state
|
|
Validate system state consistency.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Validate current system state
|
|
sudo apt-ostree internals validate-state
|
|
|
|
# Validate specific components
|
|
sudo apt-ostree internals validate-state \
|
|
--component "ostree" \
|
|
--component "apt"
|
|
```
|
|
|
|
#### Advanced Usage
|
|
```bash
|
|
# Validate with custom rules
|
|
sudo apt-ostree internals validate-state \
|
|
--rules-file /etc/apt-ostree/validation-rules.toml \
|
|
--strict-mode
|
|
|
|
# Validate and generate report
|
|
sudo apt-ostree internals validate-state \
|
|
--generate-report \
|
|
--report-format html \
|
|
--output /tmp/validation-report.html
|
|
```
|
|
|
|
#### Use Cases
|
|
- **State verification**: Verify system state consistency
|
|
- **Configuration validation**: Validate configuration files and settings
|
|
- **Pre-deployment check**: Verify system state before deployments
|
|
|
|
### debug-dump
|
|
Dump comprehensive system information for debugging.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Dump all system information
|
|
sudo apt-ostree internals debug-dump
|
|
|
|
# Dump specific information categories
|
|
sudo apt-ostree internals debug-dump \
|
|
--category "system-info" \
|
|
--category "ostree-info" \
|
|
--category "apt-info"
|
|
```
|
|
|
|
#### Advanced Usage
|
|
```bash
|
|
# Dump with custom format
|
|
sudo apt-ostree internals debug-dump \
|
|
--format json \
|
|
--output /tmp/debug-dump.json
|
|
|
|
# Dump with filtering
|
|
sudo apt-ostree internals debug-dump \
|
|
--filter "error-only" \
|
|
--include-logs \
|
|
--log-level debug
|
|
```
|
|
|
|
#### Use Cases
|
|
- **Debugging**: Comprehensive debugging information
|
|
- **Support requests**: Generate information for support requests
|
|
- **System analysis**: Analyze system configuration and state
|
|
|
|
## Common Use Cases
|
|
|
|
### Development Workflow
|
|
```bash
|
|
# 1. Check system health
|
|
sudo apt-ostree internals diagnostics
|
|
|
|
# 2. Validate system state
|
|
sudo apt-ostree internals validate-state
|
|
|
|
# 3. Test new functionality
|
|
sudo apt-ostree testutils script-shell /tmp/test-feature.sh
|
|
|
|
# 4. Generate test data
|
|
sudo apt-ostree testutils generate-synthetic-upgrade
|
|
|
|
# 5. Verify results
|
|
sudo apt-ostree internals debug-dump
|
|
```
|
|
|
|
### Troubleshooting Workflow
|
|
```bash
|
|
# 1. Run comprehensive diagnostics
|
|
sudo apt-ostree internals diagnostics --verbose
|
|
|
|
# 2. Check specific components
|
|
sudo apt-ostree shlib-backend get-basearch
|
|
sudo apt-ostree testutils moo
|
|
|
|
# 3. Validate system state
|
|
sudo apt-ostree internals validate-state --strict-mode
|
|
|
|
# 4. Generate debug report
|
|
sudo apt-ostree internals debug-dump --output /tmp/troubleshoot.json
|
|
```
|
|
|
|
### Testing Workflow
|
|
```bash
|
|
# 1. Set up test environment
|
|
sudo apt-ostree testutils script-shell /tmp/setup-test-env.sh
|
|
|
|
# 2. Run integration tests
|
|
sudo apt-ostree testutils integration-read-only
|
|
|
|
# 3. Test package operations
|
|
sudo apt-ostree testutils inject-pkglist test-commit "test-package"
|
|
|
|
# 4. Verify test results
|
|
sudo apt-ostree internals debug-dump --category "test-results"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### Permission Denied
|
|
```bash
|
|
# Check if running as root
|
|
sudo apt-ostree testutils moo
|
|
|
|
# Check Polkit policies
|
|
sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy
|
|
```
|
|
|
|
#### Command Not Found
|
|
```bash
|
|
# Verify development features are enabled
|
|
cargo build --features development
|
|
|
|
# Check if binary includes development commands
|
|
cargo run --features development -- testutils --help
|
|
```
|
|
|
|
#### Bubblewrap Issues
|
|
```bash
|
|
# Check bubblewrap installation
|
|
which bubblewrap
|
|
bubblewrap --version
|
|
|
|
# Test bubblewrap functionality
|
|
bubblewrap --dev-bind / / --proc /proc -- echo "test"
|
|
```
|
|
|
|
#### OSTree Repository Issues
|
|
```bash
|
|
# Check repository status
|
|
sudo ostree show --repo=/ostree/repo
|
|
|
|
# Verify repository integrity
|
|
sudo ostree fsck --repo=/ostree/repo
|
|
```
|
|
|
|
### Debug Mode
|
|
```bash
|
|
# Enable debug logging
|
|
export APT_OSTREE_LOG_LEVEL=debug
|
|
export RUST_LOG=debug
|
|
|
|
# Run commands with verbose output
|
|
sudo apt-ostree testutils script-shell /tmp/test.sh --verbose
|
|
```
|
|
|
|
### Log Files
|
|
- **Daemon logs**: `/var/log/apt-ostreed.log`
|
|
- **System logs**: `sudo journalctl -u apt-ostreed`
|
|
- **OSTree logs**: `sudo ostree log --repo=/ostree/repo`
|
|
|
|
## Best Practices
|
|
|
|
### Security Considerations
|
|
- **Limited access**: Only authorized users should have access to development commands
|
|
- **Isolated execution**: Use script-shell with appropriate isolation options
|
|
- **Audit trails**: Log all development command usage for audit purposes
|
|
|
|
### Performance Considerations
|
|
- **Resource limits**: Set appropriate limits for development operations
|
|
- **Timeout handling**: Use appropriate timeouts for long-running operations
|
|
- **Resource cleanup**: Ensure proper cleanup after development operations
|
|
|
|
### Development Workflow
|
|
- **Testing**: Always test development commands in isolated environments
|
|
- **Documentation**: Document custom usage patterns and configurations
|
|
- **Version control**: Track changes to development command usage
|
|
|
|
---
|
|
|
|
*This guide covers the usage of apt-ostree development commands. For general usage, refer to the main User Guide.*
|