apt-ostree/docs/development-commands-usage.md

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
2. shlib-backend Commands
3. internals Commands
4. Common Use Cases
5. Troubleshooting

testutils Commands

inject-pkglist

Inject a package list into an OSTree commit's metadata.

Basic Usage

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Verify development features are enabled
cargo build --features development

# Check if binary includes development commands
cargo run --features development -- testutils --help

Bubblewrap Issues

# Check bubblewrap installation
which bubblewrap
bubblewrap --version

# Test bubblewrap functionality
bubblewrap --dev-bind / / --proc /proc -- echo "test"

OSTree Repository Issues

# Check repository status
sudo ostree show --repo=/ostree/repo

# Verify repository integrity
sudo ostree fsck --repo=/ostree/repo

Debug Mode

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