diff --git a/.forgejo/workflows/ci.yml b/.forgejo/workflows/ci.yml index b4100ccf..80a11ce6 100644 --- a/.forgejo/workflows/ci.yml +++ b/.forgejo/workflows/ci.yml @@ -26,9 +26,17 @@ jobs: echo "Testing secret priority:" echo "TEST_SECRET value: ${{ secrets.TEST_SECRET }}" echo "User level: apple" - echo "Org level: pear" + echo "Org level: pear" echo "Repo level: pumpkin" + echo "" + echo "Available environment variables:" + echo "GITEA_RUN_NUMBER: ${GITEA_RUN_NUMBER:-'NOT_SET'}" + echo "ACTIONS_RUN_NUMBER: ${ACTIONS_RUN_NUMBER:-'NOT_SET'}" + echo "GITHUB_RUN_NUMBER: ${GITHUB_RUN_NUMBER:-'NOT_SET'}" + echo "RUNNER_OS: ${RUNNER_OS:-'NOT_SET'}" + echo "GITEA_ACTOR: ${GITEA_ACTOR:-'NOT_SET'}" + - name: Setup environment run: | # Try apt-cacher-ng first, fallback to Debian's automatic mirror selection @@ -97,7 +105,7 @@ jobs: echo "โœ… Now using clean stable Rust:" rustc --version cargo --version - + # Clear cargo cache to avoid corruption echo "๐Ÿงน Clearing cargo cache..." cargo clean @@ -115,8 +123,8 @@ jobs: echo "Building Debian package..." # Get build information for versioning - # Forgejo/Gitea Actions uses ACTIONS_RUN_NUMBER, fallback to timestamp - BUILD_NUMBER="${ACTIONS_RUN_NUMBER:-$(date +%s)}" + # Forgejo/Gitea Actions uses GITEA_RUN_NUMBER, fallback to timestamp + BUILD_NUMBER="${GITEA_RUN_NUMBER:-$(date +%s)}" COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown") BUILD_VERSION="0.1.0+build${BUILD_NUMBER}.${COMMIT_HASH}" @@ -417,8 +425,6 @@ jobs: done fi - - echo "" >> ARTIFACTS_README.md echo "## ๐Ÿ“‹ What's Included" >> ARTIFACTS_README.md echo "" >> ARTIFACTS_README.md @@ -464,8 +470,8 @@ jobs: fi # Get build info for registry - # Forgejo/Gitea Actions uses ACTIONS_RUN_NUMBER, fallback to timestamp - BUILD_NUMBER="${ACTIONS_RUN_NUMBER:-$(date +%s)}" + # Forgejo/Gitea Actions uses GITEA_RUN_NUMBER, fallback to timestamp + BUILD_NUMBER="${GITEA_RUN_NUMBER:-$(date +%s)}" COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown") echo "Publishing packages for build $BUILD_NUMBER (commit $COMMIT_HASH)" @@ -791,5 +797,4 @@ jobs: echo "- **Build Scripts**: Automated package building and testing" >> STATUS_REPORT.md echo "Status report created: STATUS_REPORT.md" - echo "โœ… All CI jobs completed successfully!" - + echo "โœ… All CI jobs completed successfully!" \ No newline at end of file diff --git a/.forgejo/workflows/update-readme.yml b/.forgejo/workflows/update-readme.yml index ab3fb3bb..5f96815c 100644 --- a/.forgejo/workflows/update-readme.yml +++ b/.forgejo/workflows/update-readme.yml @@ -22,10 +22,10 @@ jobs: echo 'Acquire::GzipIndexes "true";' >> /etc/apt/apt.conf.d/99translations echo 'Acquire::CompressionTypes::Order:: "gz";' >> /etc/apt/apt.conf.d/99translations echo 'Dpkg::Use-Pty "0";' >> /etc/apt/apt.conf.d/99translations - + # Update package lists apt update -y - + # Install essential build tools (optimized order) apt install -y --no-install-recommends \ git curl pkg-config build-essential gnupg wget \ @@ -69,7 +69,7 @@ jobs: # Build ID: $WORKFLOW_RUN_ID # Download the .deb files and run: sudo dpkg -i apt-ostree_0.1.0-1_amd64.deb - sudo apt-get install -f # Install any missing dependencies + sudo apt-get install -f # Install missing dependencies \`\`\` ### Verification @@ -97,56 +97,3 @@ jobs: \`\`\` --- - - " > download-section.md - - # Replace the existing download section in README.md - # First, remove the old download section - sed -i '/## ๐Ÿ“ฆ Download Latest Build/,/^---$/d' README.md - - # Then insert the new download section after the first section - awk '/^## ๐Ÿš€ Quick Start/{print; print ""; system("cat download-section.md"); next} 1' README.md > README.md.tmp - mv README.md.tmp README.md - - echo "README updated with download links for workflow run $WORKFLOW_RUN_ID" - - - name: Commit and push changes - run: | - # Configure git - git config --global user.email "action@github.com" - git config --global user.name "GitHub Action" - - # Add and commit changes - git add README.md - git commit -m "Update README with download links for build $(date +%s)" - - # Push changes - git push origin main - - - name: Create update summary - run: | - echo "Creating update summary..." - - # Create a summary markdown file - echo " - # README Update Summary - - ## Update Information - - **Update Date**: $(date '+%Y-%m-%d %H:%M:%S UTC') - - **Triggered by**: Build workflow $(date +%s) - - **Status**: โœ… SUCCESS - - ## Changes Made - - Updated download section with latest build links - - Updated target platform from Ubuntu Noble to Debian Stable - - Updated build ID reference - - Maintained all existing functionality - - ## Next Steps - - README has been automatically updated - - Changes have been committed and pushed to main branch - - Users can now access the latest build information - " > UPDATE_SUMMARY.md - - echo "Update summary created: UPDATE_SUMMARY.md" - echo "README update completed successfully! ๐ŸŽ‰" diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 70df817d..795a75bd 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -2,41 +2,41 @@ name: Build and Upload apt-ostree Debian Package on: push: - branches: [ main ] + branches: [main] pull_request: - branches: [ main ] + branches: [main] release: - types: [ published ] + types: [published] jobs: build: runs-on: ubuntu-24.04 - + steps: - - uses: actions/checkout@v4 - - - name: Install dependencies - run: | - sudo apt update - sudo apt install -y build-essential devscripts debhelper dh-cargo cargo rustc pkg-config - sudo apt install -y libostree-dev libglib2.0-dev libcurl4-gnutls-dev libssl-dev libsystemd-dev libmount-dev libselinux1-dev - - - name: Build package - run: | - ./build.sh - - - name: Upload artifacts - uses: actions/upload-artifact@v4 - with: - name: apt-ostree-deb-packages - path: output/ - - - name: Upload to Forgejo (on release) - if: github.event_name == 'release' - run: | - # Upload to Forgejo Debian repository - # This would use your Forgejo API token - echo "Uploading to Forgejo repository..." - # curl -X POST -H "Authorization: token ${{ secrets.FORGEJO_TOKEN }}" \ - # -F "package=@output/apt-ostree_*.deb" \ - # https://git.raines.xyz/api/packages/robojerk/debian/upload \ No newline at end of file + - uses: actions/checkout@v4 + + - name: Install dependencies + run: | + sudo apt update + sudo apt install -y build-essential devscripts debhelper dh-cargo cargo rustc pkg-config + sudo apt install -y libostree-dev libglib2.0-dev libcurl4-gnutls-dev libssl-dev libsystemd-dev libmount-dev libselinux1-dev + + - name: Build package + run: | + ./build.sh + + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: apt-ostree-deb-packages + path: output/ + + - name: Upload to Forgejo (on release) + if: github.event_name == 'release' + run: | + # Upload to Forgejo Debian repository + # This would use your Forgejo API token + echo "Uploading to Forgejo repository..." + # curl -X POST -H "Authorization: token ${{ secrets.FORGEJO_TOKEN }}" \ + # -F "package=@output/apt-ostree_*.deb" \ + # https://git.raines.xyz/api/packages/robojerk/debian/upload diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 59577ef5..70626688 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,322 +1,181 @@ -name: CI +--- +name: CI/CD Pipeline on: push: - branches: [ main, develop ] + branches: [main, develop] pull_request: - branches: [ main ] + branches: [main, develop] env: CARGO_TERM_COLOR: always RUST_BACKTRACE: 1 jobs: - # Build and test on multiple platforms test: + name: Test + runs-on: "ubuntu-latest" strategy: - fail-fast: false matrix: - include: - - name: "Debian Trixie (x86_64)" - os: ubuntu-22.04 - rust: stable - target: x86_64-unknown-linux-gnu - container: debian:trixie - - name: "Ubuntu Noble (x86_64)" - os: ubuntu-22.04 - rust: stable - target: x86_64-unknown-linux-gnu - container: ubuntu:noble - - name: "Debian Trixie (aarch64)" - os: ubuntu-22.04 - rust: stable - target: aarch64-unknown-linux-gnu - container: debian:trixie - - runs-on: ${{ matrix.os }} - container: ${{ matrix.container }} + rust: [stable, 1.75] + features: [default, development, dev-full] steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - submodules: recursive + - name: Checkout code + uses: actions/checkout@v4 - - name: Install system dependencies - run: | - apt-get update - apt-get install -y \ - build-essential \ - pkg-config \ - libssl-dev \ - libdbus-1-dev \ - libglib2.0-dev \ - libpolkit-gobject-1-dev \ - ostree \ - bubblewrap \ - curl \ - git + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable + with: + toolchain: ${{ matrix.rust }} - - name: Install Rust toolchain - uses: actions-rs/toolchain@v1 - with: - toolchain: ${{ matrix.rust }} - target: ${{ matrix.target }} - override: true + - name: Cache Rust dependencies + uses: Swatinem/rust-cache@v2 - - name: Cache Rust dependencies - uses: actions/cache@v3 - with: - path: | - ~/.cargo/registry - ~/.cargo/git - target - key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} + - name: Install system dependencies + run: | + sudo apt-get update + sudo apt-get install -y \ + libostree-1-dev \ + libapt-pkg-dev \ + libpolkit-gobject-1-dev \ + bubblewrap \ + binutils \ + pkg-config \ + build-essential - - name: Build project - run: | - cargo build --target ${{ matrix.target }} --verbose + - name: Check code formatting + run: cargo fmt --all -- --check - - name: Run unit tests - run: | - cargo test --target ${{ matrix.target }} --verbose + - name: Run Clippy + run: cargo clippy --features ${{ matrix.features }} -- -D warnings - - name: Run integration tests - run: | - cargo test --target ${{ matrix.target }} --test integration_tests --verbose + - name: Run tests + run: cargo test --features ${{ matrix.features }} - - name: Check code quality - run: | - cargo clippy --target ${{ matrix.target }} -- -D warnings - cargo fmt --target ${{ matrix.target }} -- --check + - name: Build release + run: cargo build --release --features ${{ matrix.features }} - # Security and quality checks - security: - runs-on: ubuntu-22.04 - container: debian:trixie + - name: Test development commands + if: matrix.features != 'default' + run: | + cargo run --features ${{ matrix.features }} -- testutils --help + cargo run --features ${{ matrix.features }} -- shlib-backend --help + cargo run --features ${{ matrix.features }} -- internals --help + + build-debian: + name: Build Debian Package + runs-on: "ubuntu-latest" + needs: test + if: github.event_name == 'push' && github.ref == 'refs/heads/main' steps: - - name: Checkout code - uses: actions/checkout@v4 + - name: Checkout code + uses: actions/checkout@v4 - - name: Install Rust toolchain - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - override: true + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable - - name: Install security tools - run: | - apt-get update - apt-get install -y cargo-audit + - name: Install build dependencies + run: | + sudo apt-get update + sudo apt-get install -y \ + libostree-1-dev \ + libapt-pkg-dev \ + libpolkit-gobject-1-dev \ + bubblewrap \ + binutils \ + pkg-config \ + build-essential \ + devscripts \ + debhelper \ + dh-cargo - - name: Run security audit - run: | - cargo audit --version - cargo audit + - name: Build Debian package + run: | + ./build-debian-trixie.sh - - name: Check for known vulnerabilities - run: | - cargo audit --deny warnings + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: debian-package + path: | + *.deb + *.dsc + *.tar.* - # Performance benchmarking - benchmark: - runs-on: ubuntu-22.04 - container: debian:trixie + security-audit: + name: Security Audit + runs-on: "ubuntu-latest" + strategy: + matrix: + rust: [stable] steps: - - name: Checkout code - uses: actions/checkout@v4 + - name: Checkout code + uses: actions/checkout@v4 - - name: Install Rust toolchain - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - override: true + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable + with: + toolchain: ${{ matrix.rust }} - - name: Install benchmark dependencies - run: | - apt-get update - apt-get install -y \ - build-essential \ - pkg-config \ - libssl-dev \ - libdbus-1-dev \ - libglib2.0-dev \ - libpolkit-gobject-1-dev + - name: Install cargo-audit + run: cargo install cargo-audit - - name: Run performance benchmarks - run: | - cargo bench --verbose + - name: Run security audit + run: cargo audit - - name: Upload benchmark results - uses: actions/upload-artifact@v3 - with: - name: benchmark-results - path: target/criterion - - # Documentation build - docs: - runs-on: ubuntu-22.04 - container: debian:trixie + dependency-audit: + name: Dependency Audit + runs-on: "ubuntu-latest" + strategy: + matrix: + rust: [stable] steps: - - name: Checkout code - uses: actions/checkout@v4 + - name: Checkout code + uses: actions/checkout@v4 - - name: Install Rust toolchain - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - override: true + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable + with: + toolchain: ${{ matrix.rust }} - - name: Install documentation dependencies - run: | - apt-get update - apt-get install -y \ - build-essential \ - pkg-config \ - libssl-dev \ - libdbus-1-dev \ - libglib2.0-dev \ - libpolkit-gobject-1-dev + - name: Install cargo-outdated + run: cargo install cargo-outdated - - name: Build documentation - run: | - cargo doc --no-deps --verbose + - name: Check for outdated dependencies + run: cargo outdated - - name: Upload documentation - uses: actions/upload-artifact@v3 - with: - name: documentation - path: target/doc - - # Debian package build - debian-package: - runs-on: ubuntu-22.04 - container: debian:trixie + documentation: + name: Build Documentation + runs-on: "ubuntu-latest" + strategy: + matrix: + features: [default, development] steps: - - name: Checkout code - uses: actions/checkout@v4 + - name: Checkout code + uses: actions/checkout@v4 - - name: Install build dependencies - run: | - apt-get update - apt-get install -y \ - build-essential \ - devscripts \ - debhelper \ - dh-cargo \ - cargo \ - pkg-config \ - libssl-dev \ - libdbus-1-dev \ - libglib2.0-dev \ - libpolkit-gobject-1-dev + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable - - name: Build Debian package - run: | - ./build-debian-trixie.sh + - name: Install system dependencies + run: | + sudo apt-get update + sudo apt-get install -y \ + libostree-1-dev \ + libapt-pkg-dev \ + libpolkit-gobject-1-dev \ + pkg-config - - name: Upload Debian package - uses: actions/upload-artifact@v3 - with: - name: debian-package - path: deb_packages/ + - name: Build documentation + run: cargo doc --features ${{ matrix.features }} --no-deps - # Integration testing with real OSTree - ostree-integration: - runs-on: ubuntu-22.04 - container: debian:trixie - - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Install Rust toolchain - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - override: true - - - name: Install OSTree testing dependencies - run: | - apt-get update - apt-get install -y \ - build-essential \ - pkg-config \ - libssl-dev \ - libdbus-1-dev \ - libglib2.0-dev \ - libpolkit-gobject-1-dev \ - ostree \ - bubblewrap \ - qemu-system-x86_64 \ - qemu-utils - - - name: Build apt-ostree - run: | - cargo build --release - - - name: Run OSTree integration tests - run: | - # Test with real OSTree repository - mkdir -p /tmp/test-ostree - ostree init --repo=/tmp/test-ostree - ./target/release/apt-ostree status - - - name: Upload test artifacts - uses: actions/upload-artifact@v3 - with: - name: ostree-test-results - path: /tmp/test-ostree/ - - # Code coverage - coverage: - runs-on: ubuntu-22.04 - container: debian:trixie - - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Install Rust toolchain - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - override: true - - - name: Install coverage tools - run: | - apt-get update - apt-get install -y \ - build-essential \ - pkg-config \ - libssl-dev \ - libdbus-1-dev \ - libglib2.0-dev \ - libpolkit-gobject-1-dev \ - cargo-tarpaulin - - - name: Generate coverage report - run: | - cargo tarpaulin --out Html --output-dir coverage - - - name: Upload coverage report - uses: actions/upload-artifact@v3 - with: - name: coverage-report - path: coverage/ - - # Final status check - status: - needs: [test, security, benchmark, docs, debian-package, ostree-integration, coverage] - runs-on: ubuntu-latest - if: always() - - steps: - - name: Check job status - run: | - echo "All CI jobs completed" - echo "Check individual job results above" + - name: Upload documentation + uses: actions/upload-artifact@v4 + with: + name: docs-${{ matrix.features }} + path: target/doc/ diff --git a/.yamllint b/.yamllint new file mode 100644 index 00000000..0a6253a9 --- /dev/null +++ b/.yamllint @@ -0,0 +1,6 @@ +extends: default + +rules: + truthy: + check-keys: false + document-start: disable diff --git a/Cargo.toml b/Cargo.toml index bea20cca..aa2fdd55 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -24,6 +24,9 @@ num_cpus = "1.16" anyhow = "1.0" thiserror = "1.0" +# Command line argument parsing +clap = { version = "4.0", features = ["derive"] } + # Serialization (used extensively) serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" @@ -71,6 +74,12 @@ sha256 = "1.0" futures = "0.3" async-trait = "0.1" +# Development commands dependencies +goblin = { version = "0.8", optional = true } # ELF file manipulation +rand = { version = "0.8", optional = true } # Random number generation +cap-std = { version = "1.0", optional = true } # Capability-based file operations +cap-std-ext = { version = "1.0", optional = true } # Extended capability operations + [build-dependencies] pkg-config = "0.3" @@ -83,6 +92,11 @@ codegen-units = 1 opt-level = 0 debug = true +[features] +default = [] +development = ["goblin", "rand", "cap-std", "cap-std-ext"] +dev-full = ["development", "cap-std", "cap-std-ext"] + [[bin]] name = "apt-ostree" path = "src/main.rs" diff --git a/PACKAGE_MERGE_SUMMARY.md b/PACKAGE_MERGE_SUMMARY.md new file mode 100644 index 00000000..27d38aba --- /dev/null +++ b/PACKAGE_MERGE_SUMMARY.md @@ -0,0 +1,123 @@ +# apt-ostree Package Merge Summary + +## Overview +Successfully merged the separate `apt-ostree` (CLI tool) and `apt-ostreed` (daemon) packages into a single `apt-ostree` package. This simplifies installation, dependency management, and maintenance. + +## Changes Made + +### 1. **debian/control** +- Removed the separate `apt-ostreed` package +- Updated main `apt-ostree` package description to mention it contains both components +- Added `polkitd` and `dbus` dependencies directly to the main package +- Removed circular dependency between packages + +### 2. **debian/rules** +- Modified installation rules to install both binaries into single package directory +- All daemon files (systemd services, polkit policies, config files) now go into main package +- Updated paths from `debian/apt-ostreed/` to `debian/apt-ostree/` + +### 3. **debian/apt-ostree.postinst** +- Added daemon service setup functionality (`setup_service`) +- Added directory creation and permission setup (`setup_directories`) +- Added polkit rules reloading (`reload_polkit`) +- Removed dependency check for separate `apt-ostreed` package +- Integrated both CLI and daemon setup logic + +### 4. **debian/apt-ostree.postrm** +- Added daemon service cleanup (`cleanup_daemon`) +- Added daemon file cleanup on purge (`cleanup_daemon_files`) +- Integrated both CLI and daemon cleanup logic + +### 5. **debian/apt-ostree.prerm** +- Added daemon service stopping before removal +- Added daemon configuration backup functionality +- Enhanced backup to include both CLI and daemon configs + +### 6. **debian/apt-ostree.triggers** +- Merged daemon triggers (polkit, systemd, D-Bus) into main package triggers +- Added triggers for `/usr/share/polkit-1/actions`, `/lib/systemd/system`, and `/usr/share/dbus-1/system-services` + +### 7. **debian/apt-ostree.conffiles** +- Created new conffiles file for the main package +- Added daemon configuration file as a conffile: `/etc/apt-ostreed/apt-ostreed.conf` + +### 8. **Cleaned up old files** +- Removed `debian/apt-ostreed.postinst` +- Removed `debian/apt-ostreed.postrm` +- Removed `debian/apt-ostreed.triggers` +- Removed `debian/apt-ostreed.conffiles` +- Removed `debian/apt-ostreed.substvars` + +## Package Contents + +The new single `apt-ostree` package now contains: + +### CLI Components +- `/usr/bin/apt-ostree` - Main CLI binary +- `/usr/share/man/man1/apt-ostree.1` - Manual page +- `/usr/share/bash-completion/completions/apt-ostree` - Bash completion +- `/usr/share/zsh/vendor-completions/_apt-ostree` - Zsh completion + +### Daemon Components +- `/usr/libexec/apt-ostreed` - Daemon binary +- `/lib/systemd/system/apt-ostreed.service` - Systemd service +- `/lib/systemd/system/apt-ostreed.socket` - Systemd socket +- `/usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy` - Polkit policy +- `/etc/apt-ostreed/apt-ostreed.conf` - Daemon configuration + +### System Integration +- `/var/log/apt-ostreed` - Log directory +- `/var/cache/apt-ostree` - Cache directory +- `/var/lib/apt-ostree` - State directory + +## Dependencies + +The single package now has these dependencies: +- `libc6 (>= 2.39)` +- `libgcc-s1 (>= 4.2)` +- `libostree-1-1 (>= 2025.2)` +- `ostree` +- `systemd` +- `libapt-pkg7.0 (>= 3.0.0)` +- `polkitd` +- `dbus` + +## Benefits + +1. **Simplified Installation**: Users only need to install one package instead of two +2. **Better Dependency Management**: No circular dependencies between packages +3. **Easier Maintenance**: Single package to maintain and update +4. **Consistent Versioning**: Both components always have the same version +5. **Cleaner Uninstallation**: Single command removes all components +6. **Reduced Package Complexity**: Fewer package files and scripts to manage + +## Build Results + +- **Package Name**: `apt-ostree_0.1.0-2_amd64.deb` +- **Size**: ~1.6 MB (includes both CLI and daemon) +- **Build Status**: โœ… Successful +- **Installation**: Both components install from single package +- **Service Management**: Daemon service automatically configured and started + +## Testing + +The package has been successfully built and verified to contain: +- โœ… CLI binary (`apt-ostree`) +- โœ… Daemon binary (`apt-ostreed`) +- โœ… Systemd service files +- โœ… Polkit policies +- โœ… Configuration files +- โœ… All necessary directories and permissions + +## Future Considerations + +1. **Version Management**: Both components will always be updated together +2. **Configuration**: Single package makes configuration management simpler +3. **Rollbacks**: Package rollbacks affect both components simultaneously +4. **Testing**: Integration testing can be simplified with single package + +--- + +**Date**: 2025-08-17 +**Status**: Complete +**Next Steps**: Test installation and functionality on target systems diff --git a/README.md b/README.md index 75188bcb..bf54c57c 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ # apt-ostree -Debian/Ubuntu equivalent of rpm-ostree for managing atomic, immutable deployments using OSTree. +A Debian/Ubuntu equivalent of `rpm-ostree` for atomic, immutable deployments. -## ๐ŸŽฏ What is apt-ostree? +## ๐ŸŽฏ **Project Goal** +Make apt-ostree a **1:1 equivalent** of rpm-ostree for Debian systems, with identical CLI interface and functionality adapted for the Debian/Ubuntu ecosystem. -`apt-ostree` is a tool that brings the benefits of atomic, immutable operating systems to Debian and Ubuntu systems. It provides functionality similar to `rpm-ostree` but adapted for APT package management, enabling: - -- **Atomic updates** - System updates happen atomically with rollback capability -- **Immutable base system** - Core system files are read-only and versioned -- **Layered package management** - Additional packages can be layered on top -- **OSTree integration** - Uses OSTree for filesystem management and versioning +## ๐Ÿ“‹ **Requirements** +- Debian Trixie (13) or Forky (14), or Ubuntu 25.04+ (Noble Numbat) or newer +- OSTree 2025.2+ +- APT 3.0+ +- Systemd 255+ +- Polkit 123+ ## ๐Ÿš€ Quick Start diff --git a/build-debian-trixie.sh b/build-debian-trixie.sh index a3c7ad3a..33e7f512 100755 --- a/build-debian-trixie.sh +++ b/build-debian-trixie.sh @@ -106,6 +106,26 @@ else exit 1 fi +# Test development features +print_status "Testing development features..." +cargo build --features development --release + +if [ $? -eq 0 ]; then + print_success "Development features build successful" +else + print_error "Development features build failed" + exit 1 +fi + +# Test development commands +print_status "Testing development commands..." +if cargo run --features development -- testutils --help >/dev/null 2>&1; then + print_success "Development commands working correctly" +else + print_error "Development commands failed" + exit 1 +fi + # Build the Debian package print_status "Building Debian package..." dpkg-buildpackage -us -uc -b diff --git a/debian/apt-ostreed.conffiles b/debian/apt-ostree.conffiles similarity index 100% rename from debian/apt-ostreed.conffiles rename to debian/apt-ostree.conffiles diff --git a/debian/apt-ostree.postinst b/debian/apt-ostree.postinst index 990e2e17..fb318ae4 100755 --- a/debian/apt-ostree.postinst +++ b/debian/apt-ostree.postinst @@ -28,15 +28,81 @@ setup_completions() { fi } +# Function to check if systemd is available +check_systemd() { + if ! command -v systemctl >/dev/null 2>&1; then + log "Warning: systemd not available, skipping service setup" + return 1 + fi + return 0 +} + +# Function to enable and start the service +setup_service() { + if ! check_systemd; then + return 0 + fi + + log "Setting up apt-ostreed service..." + + # Reload systemd daemon + systemctl daemon-reload + + # Enable the service + if systemctl enable apt-ostreed.service; then + log "apt-ostreed service enabled" + else + log "Warning: Failed to enable apt-ostreed service" + fi + + # Start the service if not running + if ! systemctl is-active --quiet apt-ostreed.service; then + if systemctl start apt-ostreed.service; then + log "apt-ostreed service started" + else + log "Warning: Failed to start apt-ostreed service" + fi + else + log "apt-ostreed service already running" + fi +} + +# Function to setup directories and permissions +setup_directories() { + log "Setting up directories and permissions..." + + # Create necessary directories with proper permissions + mkdir -p /var/log/apt-ostreed + mkdir -p /var/cache/apt-ostree + mkdir -p /var/lib/apt-ostree + mkdir -p /var/lib/apt-ostree/repo + + # Set proper ownership (root:root) + chown root:root /var/log/apt-ostreed + chown root:root /var/cache/apt-ostree + chown root:root /var/lib/apt-ostree + chown root:root /var/lib/apt-ostree/repo + + # Set proper permissions + chmod 755 /var/log/apt-ostreed + chmod 755 /var/cache/apt-ostree + chmod 755 /var/lib/apt-ostree + chmod 755 /var/lib/apt-ostree/repo +} + +# Function to reload polkit rules +reload_polkit() { + if command -v pkaction >/dev/null 2>&1; then + log "Reloading polkit rules..." + # This will trigger polkit to reload its rules + pkaction --version >/dev/null 2>&1 || true + fi +} + # Function to check dependencies check_dependencies() { log "Checking dependencies..." - # Check if apt-ostreed is installed and running - if ! dpkg -l apt-ostreed >/dev/null 2>&1; then - log "Warning: apt-ostreed package not found. Some features may not work." - fi - # Check if ostree is available if ! command -v ostree >/dev/null 2>&1; then log "Warning: ostree command not found. Please install ostree package." @@ -53,6 +119,9 @@ case "$1" in configure) log "Configuring apt-ostree package..." setup_completions + setup_directories + setup_service + reload_polkit check_dependencies log "Configuration completed successfully" ;; diff --git a/debian/apt-ostree.postrm b/debian/apt-ostree.postrm index 3f9a424c..ca9ca1ac 100755 --- a/debian/apt-ostree.postrm +++ b/debian/apt-ostree.postrm @@ -47,15 +47,73 @@ cleanup_man_pages() { fi } +# Function to cleanup daemon service +cleanup_daemon() { + log "Cleaning up apt-ostreed daemon..." + + # Check if systemd is available + if ! command -v systemctl >/dev/null 2>&1; then + log "Warning: systemd not available, skipping service cleanup" + return 0 + fi + + # Stop the service if running + if systemctl is-active --quiet apt-ostreed.service; then + log "Stopping apt-ostreed service..." + systemctl stop apt-ostreed.service || true + fi + + # Disable the service + if systemctl is-enabled --quiet apt-ostreed.service; then + log "Disabling apt-ostreed service..." + systemctl disable apt-ostreed.service || true + fi + + # Reload systemd daemon + systemctl daemon-reload || true +} + +# Function to cleanup daemon files +cleanup_daemon_files() { + log "Cleaning up daemon files..." + + # Remove systemd service files + if [ -f /lib/systemd/system/apt-ostreed.service ]; then + rm -f /lib/systemd/system/apt-ostreed.service + fi + + if [ -f /lib/systemd/system/apt-ostreed.socket ]; then + rm -f /lib/systemd/system/apt-ostreed.socket + fi + + # Remove polkit policy + if [ -f /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy ]; then + rm -f /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy + fi + + # Remove configuration files + if [ -d /etc/apt-ostreed ]; then + rm -rf /etc/apt-ostreed + fi + + # Remove binary + if [ -f /usr/libexec/apt-ostreed ]; then + rm -f /usr/libexec/apt-ostreed + fi +} + # Main execution case "$1" in remove|upgrade|failed-upgrade|abort-install|abort-upgrade|disappear) cleanup_completions cleanup_man_pages + cleanup_daemon ;; purge) cleanup_completions cleanup_man_pages + cleanup_daemon + cleanup_daemon_files ;; *) log "Unknown action: $1" diff --git a/debian/apt-ostree.postrm.debhelper b/debian/apt-ostree.postrm.debhelper new file mode 100644 index 00000000..72131c8e --- /dev/null +++ b/debian/apt-ostree.postrm.debhelper @@ -0,0 +1,12 @@ +# Automatically added by dh_installsystemd/13.24.2 +if [ "$1" = remove ] && [ -d /run/systemd/system ] ; then + systemctl --system daemon-reload >/dev/null || true +fi +# End automatically added section +# Automatically added by dh_installsystemd/13.24.2 +if [ "$1" = "purge" ]; then + if [ -x "/usr/bin/deb-systemd-helper" ]; then + deb-systemd-helper purge 'apt-ostreed.service' 'apt-ostreed.socket' >/dev/null || true + fi +fi +# End automatically added section diff --git a/debian/apt-ostree.prerm b/debian/apt-ostree.prerm index ba5b6175..2a9aaa09 100755 --- a/debian/apt-ostree.prerm +++ b/debian/apt-ostree.prerm @@ -12,6 +12,7 @@ PACKAGE="apt-ostree" # Configuration directories CONFIG_DIR="/etc/apt-ostree" +DAEMON_CONFIG_DIR="/etc/apt-ostreed" DATA_DIR="/var/lib/apt-ostree" LOG_DIR="/var/log/apt-ostree" @@ -48,6 +49,14 @@ case "$1" in fi fi + # Stop the apt-ostreed daemon service if running + if command -v systemctl >/dev/null 2>&1; then + if systemctl is-active --quiet apt-ostreed.service; then + echo "Stopping apt-ostreed service..." + systemctl stop apt-ostreed.service || true + fi + fi + # Stop any running apt-ostree processes if pgrep -f "apt-ostree" >/dev/null 2>&1; then echo "Stopping running apt-ostree processes..." @@ -65,6 +74,11 @@ case "$1" in cp -r "$CONFIG_DIR" "/tmp/apt-ostree-backup-$(date +%Y%m%d-%H%M%S)/" || true echo "Configuration backed up to /tmp/apt-ostree-backup-*" fi + if [ -d "$DAEMON_CONFIG_DIR" ]; then + mkdir -p "/tmp/apt-ostree-backup-$(date +%Y%m%d-%H%M%S)" + cp -r "$DAEMON_CONFIG_DIR" "/tmp/apt-ostree-backup-$(date +%Y%m%d-%H%M%S)/" || true + echo "Daemon configuration backed up to /tmp/apt-ostree-backup-*" + fi fi echo "$PACKAGE pre-removal completed" diff --git a/debian/apt-ostree.triggers b/debian/apt-ostree.triggers index c6f154b0..8bad48aa 100644 --- a/debian/apt-ostree.triggers +++ b/debian/apt-ostree.triggers @@ -7,3 +7,12 @@ interest-noawait /usr/share/zsh/vendor-completions # Trigger when man pages are updated interest-noawait /usr/share/man + +# Trigger when polkit rules are updated +interest-noawait /usr/share/polkit-1/actions + +# Trigger when systemd units are updated +interest-noawait /lib/systemd/system + +# Trigger when D-Bus configuration is updated +interest-noawait /usr/share/dbus-1/system-services diff --git a/debian/apt-ostree/DEBIAN/conffiles b/debian/apt-ostree/DEBIAN/conffiles new file mode 100644 index 00000000..eb1d19fa --- /dev/null +++ b/debian/apt-ostree/DEBIAN/conffiles @@ -0,0 +1,2 @@ +/etc/apt-ostreed/apt-ostreed.conf +/etc/apt-ostreed/apt-ostreed.conf diff --git a/debian/apt-ostree/DEBIAN/control b/debian/apt-ostree/DEBIAN/control index 0a919a36..8b8ea252 100644 --- a/debian/apt-ostree/DEBIAN/control +++ b/debian/apt-ostree/DEBIAN/control @@ -2,8 +2,8 @@ Package: apt-ostree Version: 0.1.0-2 Architecture: amd64 Maintainer: Robojerk -Installed-Size: 3655 -Depends: libc6 (>= 2.39), libgcc-s1 (>= 4.2), libostree-1-1 (>= 2025.2), ostree, systemd, libapt-pkg7.0 (>= 3.0.0), apt-ostreed (= 0.1.0-2) +Installed-Size: 6525 +Depends: libc6 (>= 2.39), libgcc-s1 (>= 4.2), libostree-1-1 (>= 2025.2), ostree, systemd, libapt-pkg7.0 (>= 3.0.0), polkitd, dbus Section: admin Priority: optional Homepage: https://github.com/robojerk/apt-ostree @@ -15,4 +15,9 @@ Description: Debian/Ubuntu equivalent of rpm-ostree APT package management, enabling atomic updates and rollbacks on Debian-based systems. . - This package contains the command-line interface and user tools. + This package contains both the command-line interface and the + system daemon (apt-ostreed) that provides DBus interface for + system management operations. + . + The daemon runs with elevated privileges and provides secure + access to system management functions through D-Bus. diff --git a/debian/apt-ostree/DEBIAN/md5sums b/debian/apt-ostree/DEBIAN/md5sums index 0acc9390..d3c87c62 100644 --- a/debian/apt-ostree/DEBIAN/md5sums +++ b/debian/apt-ostree/DEBIAN/md5sums @@ -1,8 +1,12 @@ -fdb041b5a80001bc08f3f94bcb3daf37 usr/bin/apt-ostree +a485e242b07f321593e7711f9f7b43d7 lib/systemd/system/apt-ostreed.service +bd58c49830864047894e04d986d850db lib/systemd/system/apt-ostreed.socket +4fefc30bb5f348ff65663f7677cd69d8 usr/bin/apt-ostree +4a710566895db1003adccd614e0c8aca usr/libexec/apt-ostreed 3aa6e44bf07699d5bd7a2e5b3d66ce65 usr/share/bash-completion/completions/apt-ostree 3147ea2bb732b3d1e98d33a23349aafd usr/share/doc/apt-ostree/README.Debian ef4534c1d6bff0d781fd07636f4dec03 usr/share/doc/apt-ostree/changelog.Debian.gz 25df758a27389af0cfd52f4dce60ccce usr/share/doc/apt-ostree/copyright 1699c458f49ca15357c5855075e0eee6 usr/share/lintian/overrides/apt-ostree e2cca69674af05683b8aa52427a840e8 usr/share/man/man1/apt-ostree.1.gz +863ffbba8bf3105e2cb0c34c90bf5cbe usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy d057f9ea83226bd3e48795fac1e224b6 usr/share/zsh/vendor-completions/_apt-ostree diff --git a/debian/apt-ostree/DEBIAN/postinst b/debian/apt-ostree/DEBIAN/postinst index 990e2e17..fb318ae4 100755 --- a/debian/apt-ostree/DEBIAN/postinst +++ b/debian/apt-ostree/DEBIAN/postinst @@ -28,15 +28,81 @@ setup_completions() { fi } +# Function to check if systemd is available +check_systemd() { + if ! command -v systemctl >/dev/null 2>&1; then + log "Warning: systemd not available, skipping service setup" + return 1 + fi + return 0 +} + +# Function to enable and start the service +setup_service() { + if ! check_systemd; then + return 0 + fi + + log "Setting up apt-ostreed service..." + + # Reload systemd daemon + systemctl daemon-reload + + # Enable the service + if systemctl enable apt-ostreed.service; then + log "apt-ostreed service enabled" + else + log "Warning: Failed to enable apt-ostreed service" + fi + + # Start the service if not running + if ! systemctl is-active --quiet apt-ostreed.service; then + if systemctl start apt-ostreed.service; then + log "apt-ostreed service started" + else + log "Warning: Failed to start apt-ostreed service" + fi + else + log "apt-ostreed service already running" + fi +} + +# Function to setup directories and permissions +setup_directories() { + log "Setting up directories and permissions..." + + # Create necessary directories with proper permissions + mkdir -p /var/log/apt-ostreed + mkdir -p /var/cache/apt-ostree + mkdir -p /var/lib/apt-ostree + mkdir -p /var/lib/apt-ostree/repo + + # Set proper ownership (root:root) + chown root:root /var/log/apt-ostreed + chown root:root /var/cache/apt-ostree + chown root:root /var/lib/apt-ostree + chown root:root /var/lib/apt-ostree/repo + + # Set proper permissions + chmod 755 /var/log/apt-ostreed + chmod 755 /var/cache/apt-ostree + chmod 755 /var/lib/apt-ostree + chmod 755 /var/lib/apt-ostree/repo +} + +# Function to reload polkit rules +reload_polkit() { + if command -v pkaction >/dev/null 2>&1; then + log "Reloading polkit rules..." + # This will trigger polkit to reload its rules + pkaction --version >/dev/null 2>&1 || true + fi +} + # Function to check dependencies check_dependencies() { log "Checking dependencies..." - # Check if apt-ostreed is installed and running - if ! dpkg -l apt-ostreed >/dev/null 2>&1; then - log "Warning: apt-ostreed package not found. Some features may not work." - fi - # Check if ostree is available if ! command -v ostree >/dev/null 2>&1; then log "Warning: ostree command not found. Please install ostree package." @@ -53,6 +119,9 @@ case "$1" in configure) log "Configuring apt-ostree package..." setup_completions + setup_directories + setup_service + reload_polkit check_dependencies log "Configuration completed successfully" ;; diff --git a/debian/apt-ostree/DEBIAN/postrm b/debian/apt-ostree/DEBIAN/postrm index 3f9a424c..ca9ca1ac 100755 --- a/debian/apt-ostree/DEBIAN/postrm +++ b/debian/apt-ostree/DEBIAN/postrm @@ -47,15 +47,73 @@ cleanup_man_pages() { fi } +# Function to cleanup daemon service +cleanup_daemon() { + log "Cleaning up apt-ostreed daemon..." + + # Check if systemd is available + if ! command -v systemctl >/dev/null 2>&1; then + log "Warning: systemd not available, skipping service cleanup" + return 0 + fi + + # Stop the service if running + if systemctl is-active --quiet apt-ostreed.service; then + log "Stopping apt-ostreed service..." + systemctl stop apt-ostreed.service || true + fi + + # Disable the service + if systemctl is-enabled --quiet apt-ostreed.service; then + log "Disabling apt-ostreed service..." + systemctl disable apt-ostreed.service || true + fi + + # Reload systemd daemon + systemctl daemon-reload || true +} + +# Function to cleanup daemon files +cleanup_daemon_files() { + log "Cleaning up daemon files..." + + # Remove systemd service files + if [ -f /lib/systemd/system/apt-ostreed.service ]; then + rm -f /lib/systemd/system/apt-ostreed.service + fi + + if [ -f /lib/systemd/system/apt-ostreed.socket ]; then + rm -f /lib/systemd/system/apt-ostreed.socket + fi + + # Remove polkit policy + if [ -f /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy ]; then + rm -f /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy + fi + + # Remove configuration files + if [ -d /etc/apt-ostreed ]; then + rm -rf /etc/apt-ostreed + fi + + # Remove binary + if [ -f /usr/libexec/apt-ostreed ]; then + rm -f /usr/libexec/apt-ostreed + fi +} + # Main execution case "$1" in remove|upgrade|failed-upgrade|abort-install|abort-upgrade|disappear) cleanup_completions cleanup_man_pages + cleanup_daemon ;; purge) cleanup_completions cleanup_man_pages + cleanup_daemon + cleanup_daemon_files ;; *) log "Unknown action: $1" diff --git a/debian/apt-ostree/DEBIAN/prerm b/debian/apt-ostree/DEBIAN/prerm index ba5b6175..2a9aaa09 100755 --- a/debian/apt-ostree/DEBIAN/prerm +++ b/debian/apt-ostree/DEBIAN/prerm @@ -12,6 +12,7 @@ PACKAGE="apt-ostree" # Configuration directories CONFIG_DIR="/etc/apt-ostree" +DAEMON_CONFIG_DIR="/etc/apt-ostreed" DATA_DIR="/var/lib/apt-ostree" LOG_DIR="/var/log/apt-ostree" @@ -48,6 +49,14 @@ case "$1" in fi fi + # Stop the apt-ostreed daemon service if running + if command -v systemctl >/dev/null 2>&1; then + if systemctl is-active --quiet apt-ostreed.service; then + echo "Stopping apt-ostreed service..." + systemctl stop apt-ostreed.service || true + fi + fi + # Stop any running apt-ostree processes if pgrep -f "apt-ostree" >/dev/null 2>&1; then echo "Stopping running apt-ostree processes..." @@ -65,6 +74,11 @@ case "$1" in cp -r "$CONFIG_DIR" "/tmp/apt-ostree-backup-$(date +%Y%m%d-%H%M%S)/" || true echo "Configuration backed up to /tmp/apt-ostree-backup-*" fi + if [ -d "$DAEMON_CONFIG_DIR" ]; then + mkdir -p "/tmp/apt-ostree-backup-$(date +%Y%m%d-%H%M%S)" + cp -r "$DAEMON_CONFIG_DIR" "/tmp/apt-ostree-backup-$(date +%Y%m%d-%H%M%S)/" || true + echo "Daemon configuration backed up to /tmp/apt-ostree-backup-*" + fi fi echo "$PACKAGE pre-removal completed" diff --git a/debian/apt-ostree/DEBIAN/triggers b/debian/apt-ostree/DEBIAN/triggers index c6f154b0..8bad48aa 100644 --- a/debian/apt-ostree/DEBIAN/triggers +++ b/debian/apt-ostree/DEBIAN/triggers @@ -7,3 +7,12 @@ interest-noawait /usr/share/zsh/vendor-completions # Trigger when man pages are updated interest-noawait /usr/share/man + +# Trigger when polkit rules are updated +interest-noawait /usr/share/polkit-1/actions + +# Trigger when systemd units are updated +interest-noawait /lib/systemd/system + +# Trigger when D-Bus configuration is updated +interest-noawait /usr/share/dbus-1/system-services diff --git a/debian/apt-ostree/etc/apt-ostreed/apt-ostreed.conf b/debian/apt-ostree/etc/apt-ostreed/apt-ostreed.conf new file mode 100644 index 00000000..8b6a15ce --- /dev/null +++ b/debian/apt-ostree/etc/apt-ostreed/apt-ostreed.conf @@ -0,0 +1,44 @@ +# apt-ostreed Configuration File +# This file configures the apt-ostree daemon behavior + +[Daemon] +# OSTree repository path +RepoPath=/var/lib/apt-ostree/repo + +# APT configuration +AptCacheDir=/var/cache/apt-ostree +AptStateDir=/var/lib/apt-ostree/apt + +# Transaction management +TransactionTimeout=300 +MaxConcurrentTransactions=1 + +# Automatic update settings +AutomaticEnabled=false +AutomaticSecurityOnly=true +AutomaticReboot=false + +# Logging configuration +LogLevel=info +LogFile=/var/log/apt-ostreed.log + +# D-Bus configuration +DbusName=org.aptostree.dev +DbusPath=/org/aptostree/dev + +# Security settings +RequireAuthentication=true +AllowUnprivilegedRead=true + +# Debian/Ubuntu specific settings +Distribution=ubuntu +Release=24.04 +Architecture=x86_64 + +# Package management +DefaultRepositories=main,universe,multiverse,restricted +SecurityRepositories=security + +# OSTree settings +OstreeMode=bare +OstreeRef=ubuntu/24.04/x86_64 \ No newline at end of file diff --git a/debian/apt-ostree/lib/systemd/system/apt-ostreed.service b/debian/apt-ostree/lib/systemd/system/apt-ostreed.service new file mode 100644 index 00000000..d140a41c --- /dev/null +++ b/debian/apt-ostree/lib/systemd/system/apt-ostreed.service @@ -0,0 +1,30 @@ +[Unit] +Description=apt-ostree System Management Daemon +Documentation=man:apt-ostree(1) +ConditionPathExists=/ostree +RequiresMountsFor=/boot + +[Service] +# See similar code in apt-ostree-countme.service +User=apt-ostree +DynamicUser=yes +# Our primary API is DBus +Type=dbus +BusName=org.projectatomic.aptostree1 +# To use the read-only sysroot bits +MountFlags=slave +# We have no business accessing /var/roothome or /var/home +ProtectHome=true +NotifyAccess=main +# Significantly bump this timeout from the default because +# we do a lot of stuff on daemon startup. +TimeoutStartSec=5m +# We start this main process with full privileges; it may spawn unprivileged processes +# with the apt-ostree user. +ExecStart=+apt-ostree start-daemon +ExecReload=apt-ostree reload +# disable/enable downloading filelists +Environment="DOWNLOAD_FILELISTS=false" + +[Install] +WantedBy=multi-user.target diff --git a/debian/apt-ostree/lib/systemd/system/apt-ostreed.socket b/debian/apt-ostree/lib/systemd/system/apt-ostreed.socket new file mode 100644 index 00000000..3dbb6d4f --- /dev/null +++ b/debian/apt-ostree/lib/systemd/system/apt-ostreed.socket @@ -0,0 +1,12 @@ +[Unit] +Description=apt-ostree System Management Daemon Socket +Documentation=man:apt-ostree(1) + +[Socket] +ListenStream=/run/apt-ostreed.sock +SocketMode=0660 +SocketUser=apt-ostree +SocketGroup=apt-ostree + +[Install] +WantedBy=sockets.target diff --git a/debian/apt-ostree/usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy b/debian/apt-ostree/usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy new file mode 100644 index 00000000..89fe16ad --- /dev/null +++ b/debian/apt-ostree/usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy @@ -0,0 +1,143 @@ + + + + + Project Atomic + https://www.projectatomic.io/ + package-x-generic + + + Install and remove packages + Authentication is required to install and remove software + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Install local packages + Authentication is required to install software + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Override packages + Authentication is required to override base OS software + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Update base OS + Authentication is required to update software + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Update base OS + Authentication is required to update software + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Switch to a different base OS + Authentication is required to switch to a different base OS + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Rollback OS updates + Authentication is required to roll back software updates + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Change boot configuration + Authentication is required to change boot configuration + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Reload the daemon state + Authentication is required to reload the daemon + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Clean up system state + Authentication is required to clean up system state + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Manage initramfs + Authentication is required to manage initramfs + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + + Manage kernel arguments + Authentication is required to manage kernel arguments + package-x-generic + + auth_admin + auth_admin + auth_admin_keep + + + + diff --git a/debian/apt-ostreed.postinst b/debian/apt-ostreed.postinst deleted file mode 100755 index 511ace49..00000000 --- a/debian/apt-ostreed.postinst +++ /dev/null @@ -1,104 +0,0 @@ -#!/bin/sh -set -e - -# Source debconf library -. /usr/share/debconf/confmodule - -# Define package name -PACKAGE="apt-ostreed" - -# Function to log messages -log() { - echo "$PACKAGE: $1" >&2 -} - -# Function to check if systemd is available -check_systemd() { - if ! command -v systemctl >/dev/null 2>&1; then - log "Warning: systemd not available, skipping service setup" - return 1 - fi - return 0 -} - -# Function to enable and start the service -setup_service() { - if ! check_systemd; then - return 0 - fi - - log "Setting up apt-ostreed service..." - - # Reload systemd daemon - systemctl daemon-reload - - # Enable the service - if systemctl enable apt-ostreed.service; then - log "apt-ostreed service enabled" - else - log "Warning: Failed to enable apt-ostreed service" - fi - - # Start the service if not running - if ! systemctl is-active --quiet apt-ostreed.service; then - if systemctl start apt-ostreed.service; then - log "apt-ostreed service started" - else - log "Warning: Failed to start apt-ostreed service" - fi - else - log "apt-ostreed service already running" - fi -} - -# Function to setup directories and permissions -setup_directories() { - log "Setting up directories and permissions..." - - # Create necessary directories with proper permissions - mkdir -p /var/log/apt-ostreed - mkdir -p /var/cache/apt-ostree - mkdir -p /var/lib/apt-ostree - mkdir -p /var/lib/apt-ostree/repo - - # Set proper ownership (root:root) - chown root:root /var/log/apt-ostreed - chown root:root /var/cache/apt-ostree - chown root:root /var/lib/apt-ostree - chown root:root /var/lib/apt-ostree/repo - - # Set proper permissions - chmod 755 /var/log/apt-ostreed - chmod 755 /var/cache/apt-ostree - chmod 755 /var/lib/apt-ostree - chmod 755 /var/lib/apt-ostree/repo -} - -# Function to reload polkit rules -reload_polkit() { - if command -v pkaction >/dev/null 2>&1; then - log "Reloading polkit rules..." - # This will trigger polkit to reload its rules - pkaction --version >/dev/null 2>&1 || true - fi -} - -# Main execution -case "$1" in - configure) - log "Configuring apt-ostreed package..." - setup_directories - setup_service - reload_polkit - log "Configuration completed successfully" - ;; - abort-upgrade|abort-remove|abort-deconfigure) - # Do nothing on abort - ;; - *) - log "Unknown action: $1" - exit 1 - ;; -esac - -exit 0 diff --git a/debian/apt-ostreed.postrm b/debian/apt-ostreed.postrm deleted file mode 100755 index 9cf8d1f9..00000000 --- a/debian/apt-ostreed.postrm +++ /dev/null @@ -1,86 +0,0 @@ -#!/bin/sh -set -e - -# Source debconf library -. /usr/share/debconf/confmodule - -# Define package name -PACKAGE="apt-ostreed" - -# Function to log messages -log() { - echo "$PACKAGE: $1" >&2 -} - -# Function to check if systemd is available -check_systemd() { - if ! command -v systemctl >/dev/null 2>&1; then - return 1 - fi - return 0 -} - -# Function to stop and disable the service -cleanup_service() { - if ! check_systemd; then - return 0 - fi - - log "Cleaning up apt-ostreed service..." - - # Stop the service if running - if systemctl is-active --quiet apt-ostreed.service; then - if systemctl stop apt-ostreed.service; then - log "apt-ostreed service stopped" - else - log "Warning: Failed to stop apt-ostreed service" - fi - fi - - # Disable the service - if systemctl is-enabled --quiet apt-ostreed.service; then - if systemctl disable apt-ostreed.service; then - log "apt-ostreed service disabled" - else - log "Warning: Failed to disable apt-ostreed service" - fi - fi - - # Reload systemd daemon - systemctl daemon-reload -} - -# Function to cleanup directories (only on purge) -cleanup_directories() { - if [ "$1" = "purge" ]; then - log "Purging apt-ostreed directories..." - - # Remove log files (but keep directory structure) - rm -f /var/log/apt-ostreed/* - - # Remove cache files (but keep directory structure) - rm -rf /var/cache/apt-ostree/* - - # Remove state files (but keep directory structure) - rm -rf /var/lib/apt-ostree/* - - log "Directory cleanup completed" - fi -} - -# Main execution -case "$1" in - remove|upgrade|failed-upgrade|abort-install|abort-upgrade|disappear) - cleanup_service - ;; - purge) - cleanup_service - cleanup_directories "$1" - ;; - *) - log "Unknown action: $1" - exit 1 - ;; -esac - -exit 0 diff --git a/debian/apt-ostreed.substvars b/debian/apt-ostreed.substvars deleted file mode 100644 index 85ab245c..00000000 --- a/debian/apt-ostreed.substvars +++ /dev/null @@ -1,3 +0,0 @@ -shlibs:Depends=libc6 (>= 2.39), libgcc-s1 (>= 4.2) -misc:Depends= -misc:Pre-Depends= diff --git a/debian/apt-ostreed.triggers b/debian/apt-ostreed.triggers deleted file mode 100644 index 1712343d..00000000 --- a/debian/apt-ostreed.triggers +++ /dev/null @@ -1,11 +0,0 @@ -# apt-ostreed package triggers -# This file defines triggers that are activated when certain events occur - -# Trigger when polkit rules are updated -interest-noawait /usr/share/polkit-1/actions - -# Trigger when systemd units are updated -interest-noawait /lib/systemd/system - -# Trigger when D-Bus configuration is updated -interest-noawait /usr/share/dbus-1/system-services diff --git a/debian/control b/debian/control index 3e135cf5..9d529bda 100644 --- a/debian/control +++ b/debian/control @@ -18,6 +18,7 @@ Build-Depends: debhelper (>= 13), libpolkit-gobject-1-dev, libdbus-1-dev Standards-Version: 4.6.2 +Testsuite: autopkgtest-pkg-rust Homepage: https://github.com/robojerk/apt-ostree Vcs-Git: https://github.com/robojerk/apt-ostree.git Vcs-Browser: https://github.com/robojerk/apt-ostree @@ -30,7 +31,12 @@ Depends: ${shlibs:Depends}, ostree, systemd, libapt-pkg7.0 (>= 3.0.0), - apt-ostreed (= ${binary:Version}) + polkitd, + dbus +Recommends: bubblewrap, binutils +Suggests: bash-completion, zsh-common +Breaks: apt-ostree (<< 0.1.0-2) +Replaces: apt-ostree (<< 0.1.0-2) Description: Debian/Ubuntu equivalent of rpm-ostree apt-ostree is a tool for managing atomic, immutable deployments on Debian and Ubuntu systems using OSTree as the backend. @@ -39,24 +45,9 @@ Description: Debian/Ubuntu equivalent of rpm-ostree APT package management, enabling atomic updates and rollbacks on Debian-based systems. . - This package contains the command-line interface and user tools. - -Package: apt-ostreed -Architecture: any -Depends: ${shlibs:Depends}, - ${misc:Depends}, - libostree-1-1 (>= 2025.2), - ostree, - systemd, - libapt-pkg7.0 (>= 3.0.0), - polkitd, - dbus -Description: apt-ostree system management daemon - apt-ostreed is the system daemon for apt-ostree that provides - DBus interface for system management operations. - . - This package contains the daemon service and related system - integration files. + This package contains both the command-line interface and the + system daemon (apt-ostreed) that provides DBus interface for + system management operations. . The daemon runs with elevated privileges and provides secure access to system management functions through D-Bus. \ No newline at end of file diff --git a/debian/debhelper-build-stamp b/debian/debhelper-build-stamp index d78fac0a..d447e141 100644 --- a/debian/debhelper-build-stamp +++ b/debian/debhelper-build-stamp @@ -1,2 +1 @@ apt-ostree -apt-ostreed diff --git a/debian/files b/debian/files index 52ef7feb..bbfaac2c 100644 --- a/debian/files +++ b/debian/files @@ -1,5 +1,3 @@ apt-ostree-dbgsym_0.1.0-2_amd64.deb debug optional automatic=yes apt-ostree_0.1.0-2_amd64.buildinfo admin optional apt-ostree_0.1.0-2_amd64.deb admin optional -apt-ostreed-dbgsym_0.1.0-2_amd64.deb debug optional automatic=yes -apt-ostreed_0.1.0-2_amd64.deb admin optional diff --git a/debian/man/apt-ostree-dev.1 b/debian/man/apt-ostree-dev.1 new file mode 100644 index 00000000..06b05556 --- /dev/null +++ b/debian/man/apt-ostree-dev.1 @@ -0,0 +1,150 @@ +.TH APT-OSTREE-DEV 1 "2025-08-13" "apt-ostree 0.1.0" "System Administration" +.SH NAME +apt-ostree-dev \- Development and debugging commands for apt-ostree +.SH SYNOPSIS +.B apt-ostree +\fICOMMAND\fR [\fIARGS\fR] +.SH DESCRIPTION +.B apt-ostree-dev +describes the development and debugging commands available in apt-ostree. +These commands are hidden from normal help output and are intended for +developers and system administrators debugging apt-ostree installations. +.PP +These commands provide low-level access to system internals, testing utilities, +and diagnostic tools that are not part of the standard user interface. +.SH DEVELOPMENT COMMANDS +.SS "testutils" +Development and testing utilities for apt-ostree. +.TP +.B testutils inject-pkglist \fICOMMIT\fR \fIPACKAGES\fR +Inject a package list into an OSTree commit's metadata. +.TP +.B testutils script-shell \fISCRIPT\fR [\fIARGS\fR] [\fIOPTIONS\fR] +Execute a script in a bubblewrap container with various options. +.TP +.B testutils generate-synthetic-upgrade +Generate a synthetic upgrade for testing purposes. +.TP +.B testutils integration-read-only +Run integration tests in read-only mode. +.TP +.B testutils c-units +Run C unit tests if available. +.TP +.B testutils moo +Perform basic functionality tests. + +.SS "shlib-backend" +Shared library backend operations for IPC and system integration. +.TP +.B shlib-backend get-basearch +Get the system's base architecture. +.TP +.B shlib-backend varsubst-basearch \fISOURCE\fR +Perform variable substitution for architecture-specific strings. +.TP +.B shlib-backend packagelist-from-commit \fICOMMIT\fR +Extract package list from an OSTree commit. + +.SS "internals" +Internal system diagnostics and validation. +.TP +.B internals diagnostics +Run comprehensive system diagnostics. +.TP +.B internals validate-state +Validate system state consistency. +.TP +.B internals debug-dump +Dump comprehensive system information for debugging. + +.SH OPTIONS +.TP +.B \-\-rootpath \fIPATH\fR +Set the root path for script execution (default: /). +.TP +.B \-\-read-only +Execute in read-only mode. +.TP +.B \-\-user \fIUSER\fR +Execute as specified user. +.TP +.B \-\-group \fIGROUP\fR +Execute as specified group. +.TP +.B \-\-cwd \fIPATH\fR +Set working directory for execution. +.TP +.B \-\-env \fIKEY=VALUE\fR +Set environment variables. + +.SH EXAMPLES +.TP +Inject package list into commit: +.B apt-ostree testutils inject-pkglist abc123 "apt,curl,nginx" +.TP +Execute script in container: +.B apt-ostree testutils script-shell /tmp/test.sh --read-only +.TP +Get system architecture: +.B apt-ostree shlib-backend get-basearch +.TP +Run system diagnostics: +.B apt-ostree internals diagnostics + +.SH FILES +.TP +.B /usr/bin/bubblewrap +Bubblewrap binary for containerization. +.TP +.B /usr/bin/objcopy +Binutils objcopy for ELF manipulation. +.TP +.B /var/lib/apt-ostree/ +Data directory for apt-ostree. + +.SH ENVIRONMENT +.TP +.B APT_OSTREE_DEV_MODE +Enable development mode features. +.TP +.B APT_OSTREE_LOG_LEVEL +Set logging level for debugging. + +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +General error. +.TP +.B 2 +Invalid arguments. +.TP +.B 3 +System operation failed. + +.SH SECURITY +These commands provide low-level access to system internals and should only +be used by trusted administrators. The script-shell command executes code in +isolated containers, but care should be taken with the scripts being executed. + +.SH BUGS +Report bugs to the project issue tracker at +.IR https://github.com/robojerk/apt-ostree/issues . + +.SH AUTHOR +Written by Robojerk . + +.SH COPYRIGHT +Copyright \(co 2025 Robojerk. License GPL-3.0-or-later: GNU GPL version 3 or later +. +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +.SH SEE ALSO +.BR apt-ostree (1), +.BR bubblewrap (1), +.BR objcopy (1), +.BR ostree (1) diff --git a/debian/man/apt-ostree.1 b/debian/man/apt-ostree.1 new file mode 100644 index 00000000..ffa9171c --- /dev/null +++ b/debian/man/apt-ostree.1 @@ -0,0 +1,240 @@ +.TH APT-OSTREE 1 "2025-08-13" "apt-ostree 0.1.0" "System Administration" +.SH NAME +apt-ostree \- Debian/Ubuntu equivalent of rpm-ostree +.SH SYNOPSIS +.B apt-ostree +[\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR] +.SH DESCRIPTION +.B apt-ostree +is a tool for managing atomic, immutable deployments on Debian and Ubuntu systems +using OSTree as the backend. It provides functionality similar to rpm-ostree but +adapted for APT package management, enabling atomic updates and rollbacks on +Debian-based systems. +.PP +The tool integrates APT package management with OSTree's atomic deployment model, +allowing system administrators to maintain immutable system images while still +benefiting from Debian's package ecosystem. +.SH COMMANDS +.SS "Package Management Commands" +.TP +.B info \fIPACKAGE\fR +Display detailed information about a package, including dependencies, conflicts, +and metadata. +.TP +.B search \fIQUERY\fR +Search for packages in the APT repositories. +.TP +.B install \fIPACKAGES\fR +Install packages and create a new OSTree deployment. +.TP +.B remove \fIPACKAGES\fR +Remove packages and create a new OSTree deployment. +.TP +.B upgrade +Upgrade all packages and create a new OSTree deployment. +.TP +.B rollback +Rollback to the previous OSTree deployment. +.TP +.B status +Show the current OSTree deployment status. + +.SS "System Management Commands" +.TP +.B deploy \fIDEPLOYMENT\fR +Deploy a specific OSTree deployment. +.TP +.B rebase \fIREPO\fR [\fIBRANCH\fR] +Rebase to a different OSTree repository or branch. +.TP +.B cleanup +Clean up old deployments and unused objects. +.TP +.B log +Show deployment history and changes. +.TP +.B remote +Manage OSTree remotes. +.TP +.B refs +List available references in the OSTree repository. + +.SS "Kernel and Boot Commands" +.TP +.B kargs +Manage kernel command-line arguments. +.TP +.B initramfs +Manage initial RAM filesystem regeneration. + +.SS "Transaction Management Commands" +.TP +.B transaction +Manage atomic transactions for system changes. +.TP +.B start-daemon +Start the apt-ostreed system daemon. + +.SS "Development Commands (Hidden)" +.TP +.B testutils +Development and testing utilities (hidden command). +.TP +.B shlib-backend +Shared library backend operations (hidden command). +.TP +.B internals +Internal system diagnostics (hidden command). + +.SS "Experimental Commands" +.TP +.B compose +Compose new OSTree trees. +.TP +.B db +Query package database. +.TP +.B override +Manage package overrides. +.TP +.B reset +Reset system to clean state. +.TP +.B refresh-md +Refresh metadata. + +.SS "Container Commands" +.TP +.B container +Manage container operations. + +.SS "Telemetry Commands" +.TP +.B metrics +Export system metrics. +.TP +.B health +Check system health status. + +.SH OPTIONS +.TP +.B \-h, \-\-help +Show help message and exit. +.TP +.B \-V, \-\-version +Show version information and exit. +.TP +.B \-\-verbose +Enable verbose output. +.TP +.B \-\-quiet +Suppress non-error messages. +.TP +.B \-\-json +Output in JSON format. +.TP +.B \-\-pretty +Pretty-print output. + +.SH EXAMPLES +.TP +Show package information: +.B apt-ostree info apt +.TP +Search for packages: +.B apt-ostree search curl +.TP +Install a package: +.B apt-ostree install nginx +.TP +Remove a package: +.B apt-ostree remove apache2 +.TP +Upgrade all packages: +.B apt-ostree upgrade +.TP +Rollback to previous deployment: +.B apt-ostree rollback +.TP +Manage kernel arguments: +.B apt-ostree kargs --append "console=ttyS0" +.TP +Start the daemon: +.B apt-ostree start-daemon + +.SH FILES +.TP +.B /etc/apt-ostree/ +Configuration directory for apt-ostree. +.TP +.B /var/lib/apt-ostree/ +Data directory for apt-ostree. +.TP +.B /ostree/ +OSTree repository and deployments. +.TP +.B /etc/systemd/system/apt-ostreed.service +Systemd service file for the daemon. + +.SH ENVIRONMENT +.TP +.B APT_OSTREE_CONFIG +Path to configuration file (default: /etc/apt-ostree/config.toml). +.TP +.B APT_OSTREE_DATA_DIR +Path to data directory (default: /var/lib/apt-ostree). +.TP +.B APT_OSTREE_LOG_LEVEL +Log level for debugging (default: info). +.TP +.B APT_OSTREE_DAEMON_SOCKET +Path to daemon socket (default: /run/apt-ostreed.sock). + +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +General error. +.TP +.B 2 +Configuration error. +.TP +.B 3 +Package operation failed. +.TP +.B 4 +OSTree operation failed. +.TP +.B 77 +No changes detected (for --unchanged-exit-77 option). + +.SH BUGS +Report bugs to the project issue tracker at +.IR https://github.com/robojerk/apt-ostree/issues . + +.SH AUTHOR +Written by Robojerk . + +.SH COPYRIGHT +Copyright \(co 2025 Robojerk. License GPL-3.0-or-later: GNU GPL version 3 or later +. +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +.SH SEE ALSO +.BR ostree (1), +.BR apt (8), +.BR dpkg (1), +.BR rpm-ostree (1), +.BR systemctl (1), +.BR polkit (8) +.PP +The full documentation for apt-ostree is maintained as a Texinfo manual. +If the info and apt-ostree programs are properly installed at your site, +the command +.IP +.B info apt-ostree +.PP +should give you access to the complete manual. diff --git a/debian/man/apt-ostree.conf.5 b/debian/man/apt-ostree.conf.5 new file mode 100644 index 00000000..5c47a08b --- /dev/null +++ b/debian/man/apt-ostree.conf.5 @@ -0,0 +1,179 @@ +.TH APT-OSTREE.CONF 5 "2025-08-13" "apt-ostree 0.1.0" "File Formats" +.SH NAME +apt-ostree.conf \- Configuration file for apt-ostree +.SH SYNOPSIS +.B /etc/apt-ostree/config.toml +.SH DESCRIPTION +The +.B apt-ostree.conf +file contains configuration settings for apt-ostree. The file is written in TOML +format and controls various aspects of the system's behavior. +.PP +If no configuration file is specified, apt-ostree will use default values. +.SH CONFIGURATION SECTIONS +.SS "[system]" +System-wide configuration settings. +.TP +.B data_dir = \fIPATH\fR +Path to the data directory (default: /var/lib/apt-ostree). +.TP +.B log_level = \fILEVEL\fR +Logging level: debug, info, warn, error (default: info). +.TP +.B daemon_socket = \fIPATH\fR +Path to the daemon socket (default: /run/apt-ostreed.sock). +.TP +.B max_deployments = \fINUMBER\fR +Maximum number of deployments to keep (default: 3). + +.SS "[ostree]" +OSTree-specific configuration. +.TP +.B repo_path = \fIPATH\fR +Path to the OSTree repository (default: /ostree/repo). +.TP +.B deploy_path = \fIPATH\fR +Path to deployments (default: /ostree/deploy). +.TP +.B booted_deployment = \fINAME\fR +Name of the currently booted deployment. +.TP +.B default_branch = \fIBRANCH\fR +Default branch for deployments (default: debian/13/amd64). + +.SS "[apt]" +APT package management configuration. +.TP +.B sources_list = \fIPATH\fR +Path to APT sources list (default: /etc/apt/sources.list). +.TP +.B apt_conf = \fIPATH\fR +Path to APT configuration (default: /etc/apt/apt.conf). +.TP +.B cache_dir = \fIPATH\fR +APT cache directory (default: /var/cache/apt). +.TP +.B state_dir = \fIPATH\fR +APT state directory (default: /var/lib/apt). + +.SS "[security]" +Security and authentication settings. +.TP +.B polkit_enabled = \fIBOOL\fR +Enable Polkit authentication (default: true). +.TP +.B require_auth = \fIBOOL\fR +Require authentication for privileged operations (default: true). +.TP +.B allowed_users = \fIUSERS\fR +List of users allowed to perform operations. +.TP +.B allowed_groups = \fIGROUPS\fR +List of groups allowed to perform operations. + +.SS "[daemon]" +Daemon service configuration. +.TP +.B user = \fIUSER\fR +User to run the daemon as (default: root). +.TP +.B group = \fIGROUP\fR +Group to run the daemon as (default: root). +.TP +.B pid_file = \fIPATH\fR +Path to PID file (default: /run/apt-ostreed.pid). +.TP +.B log_file = \fIPATH\fR +Path to log file (default: /var/log/apt-ostreed.log). + +.SS "[development]" +Development and debugging features. +.TP +.B enable_dev_commands = \fIBOOL\fR +Enable development commands (default: false). +.TP +.B debug_mode = \fIBOOL\fR +Enable debug mode (default: false). +.TP +.B test_mode = \fIBOOL\fR +Enable test mode (default: false). + +.SH EXAMPLE CONFIGURATION +.nf +# System configuration +[system] +data_dir = "/var/lib/apt-ostree" +log_level = "info" +max_deployments = 5 + +# OSTree configuration +[ostree] +repo_path = "/ostree/repo" +deploy_path = "/ostree/deploy" +default_branch = "debian/13/amd64" + +# APT configuration +[apt] +sources_list = "/etc/apt/sources.list" +cache_dir = "/var/cache/apt" + +# Security configuration +[security] +polkit_enabled = true +require_auth = true +allowed_users = ["admin", "root"] + +# Daemon configuration +[daemon] +user = "root" +group = "root" +log_file = "/var/log/apt-ostreed.log" + +# Development features +[development] +enable_dev_commands = false +debug_mode = false +.fi + +.SH FILES +.TP +.B /etc/apt-ostree/config.toml +Default configuration file location. +.TP +.B /etc/apt-ostree/ +Configuration directory. +.TP +.B ~/.config/apt-ostree/config.toml +User-specific configuration file. + +.SH ENVIRONMENT +.TP +.B APT_OSTREE_CONFIG +Override the default configuration file path. + +.SH NOTES +The configuration file is read when apt-ostree starts. Changes to the +configuration file require restarting the daemon to take effect. +.PP +Boolean values can be specified as true/false, yes/no, or 1/0. +.PP +Paths can be absolute or relative to the configuration file location. + +.SH BUGS +Report bugs to the project issue tracker at +.IR https://github.com/robojerk/apt-ostree/issues . + +.SH AUTHOR +Written by Robojerk . + +.SH COPYRIGHT +Copyright \(co 2025 Robojerk. License GPL-3.0-or-later: GNU GPL version 3 or later +. +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +.SH SEE ALSO +.BR apt-ostree (1), +.BR apt-ostree-dev (1), +.BR ostree (1), +.BR apt (8) diff --git a/debian/rules b/debian/rules index a7a197bf..be1f2780 100755 --- a/debian/rules +++ b/debian/rules @@ -48,10 +48,19 @@ override_dh_auto_install: mkdir -p debian/apt-ostree/usr/share/zsh/vendor-completions mkdir -p debian/apt-ostree/usr/share/apt-ostree @echo "apt-ostree package directories created successfully" - # Install man page if it exists + # Install man pages if they exist @if [ -f "debian/apt-ostree.1" ]; then \ install -D -m 644 debian/apt-ostree.1 debian/apt-ostree/usr/share/man/man1/apt-ostree.1; \ fi + @if [ -f "debian/man/apt-ostree.1" ]; then \ + install -D -m 644 debian/man/apt-ostree.1 debian/apt-ostree/usr/share/man/man1/apt-ostree.1; \ + fi + @if [ -f "debian/man/apt-ostree-dev.1" ]; then \ + install -D -m 644 debian/man/apt-ostree-dev.1 debian/apt-ostree/usr/share/man/man1/apt-ostree-dev.1; \ + fi + @if [ -f "debian/man/apt-ostree.conf.5" ]; then \ + install -D -m 644 debian/man/apt-ostree.conf.5 debian/apt-ostree/usr/share/man/man5/apt-ostree.conf.5; \ + fi # Install bash completion if it exists @if [ -f "debian/apt-ostree.bash-completion" ]; then \ install -D -m 644 debian/apt-ostree.bash-completion \ @@ -63,15 +72,15 @@ override_dh_auto_install: debian/apt-ostree/usr/share/zsh/vendor-completions/_apt-ostree; \ fi - @echo "Installing apt-ostreed daemon..." + @echo "Installing apt-ostreed daemon into apt-ostree package..." # Check if binary exists @if [ ! -f "debian/cargo/target/release/apt-ostreed" ]; then \ echo "Error: apt-ostreed binary not found. Build failed."; \ exit 1; \ fi - # Install the apt-ostreed binary + # Install the apt-ostreed binary into the apt-ostree package install -D -m 755 debian/cargo/target/release/apt-ostreed \ - debian/apt-ostreed/usr/libexec/apt-ostreed + debian/apt-ostree/usr/libexec/apt-ostreed # Check and install systemd service files @if [ ! -f "daemon/systemd/apt-ostreed.service" ]; then \ echo "Error: apt-ostreed.service not found."; \ @@ -82,9 +91,9 @@ override_dh_auto_install: exit 1; \ fi install -D -m 644 daemon/systemd/apt-ostreed.service \ - debian/apt-ostreed/lib/systemd/system/apt-ostreed.service + debian/apt-ostree/lib/systemd/system/apt-ostreed.service install -D -m 644 daemon/systemd/apt-ostreed.socket \ - debian/apt-ostreed/lib/systemd/system/apt-ostreed.socket + debian/apt-ostree/lib/systemd/system/apt-ostreed.socket # Check and install polkit policy @if [ ! -f "daemon/polkit/apt-ostree.policy" ]; then \ @@ -92,24 +101,24 @@ override_dh_auto_install: exit 1; \ fi install -D -m 644 daemon/polkit/apt-ostree.policy \ - debian/apt-ostreed/usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy + debian/apt-ostree/usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy # Check and install configuration files @if [ ! -f "src/daemon/apt-ostreed.conf" ]; then \ echo "Error: apt-ostreed.conf not found."; \ exit 1; \ fi - install -d -m 755 debian/apt-ostreed/etc/apt-ostreed + install -d -m 755 debian/apt-ostree/etc/apt-ostreed install -D -m 644 src/daemon/apt-ostreed.conf \ - debian/apt-ostreed/etc/apt-ostreed/apt-ostreed.conf + debian/apt-ostree/etc/apt-ostreed/apt-ostreed.conf # Create additional directories - mkdir -p debian/apt-ostreed/usr/share/doc/apt-ostreed + mkdir -p debian/apt-ostree/usr/share/doc/apt-ostree # Create log directory - mkdir -p debian/apt-ostreed/var/log + mkdir -p debian/apt-ostree/var/log # Create cache directory - mkdir -p debian/apt-ostreed/var/cache/apt-ostree + mkdir -p debian/apt-ostree/var/cache/apt-ostree # Create state directory - mkdir -p debian/apt-ostreed/var/lib/apt-ostree - @echo "apt-ostreed package directories created successfully" + mkdir -p debian/apt-ostree/var/lib/apt-ostree + @echo "apt-ostreed components installed into apt-ostree package successfully" # Skip dh_auto_install since we've handled installation manually @echo "Package installation completed successfully!" diff --git a/docs/apt-ostree-daemon-plan/architecture/apt-library-analysis.md b/docs/apt-ostree-daemon-plan/architecture/apt-library-analysis.md index b2feb24f..68f8fe41 100644 --- a/docs/apt-ostree-daemon-plan/architecture/apt-library-analysis.md +++ b/docs/apt-ostree-daemon-plan/architecture/apt-library-analysis.md @@ -527,7 +527,7 @@ pub fn get_package(&self, name: &str) -> AptOstreeResult> { #### **Distribution Tests - ENHANCED REQUIREMENTS** - **โœ… Debian 13 Trixie**: Test in Trixie environment - **โœ… Ubuntu 25.04 Plucky Puffin**: Test in Plucky Puffin environment -- **โœ… Backward Compatibility**: Test in current Debian 12 environment +- **โœ… Forward Compatibility**: Test in Debian 14+ (Forky) environment - **โŒ Complex Scenarios**: Test apt-ostree's core functionality - **โŒ Daemon Architecture**: Test CLI-daemon separation - **โŒ Transaction Scenarios**: Test complex transaction flows diff --git a/docs/apt-ostree-daemon-plan/development-commands-analysis.md b/docs/apt-ostree-daemon-plan/development-commands-analysis.md new file mode 100644 index 00000000..65130ffb --- /dev/null +++ b/docs/apt-ostree-daemon-plan/development-commands-analysis.md @@ -0,0 +1,224 @@ +# Development Commands Analysis: rpm-ostree Integration + +## Overview + +This document analyzes the missing development and debugging commands from rpm-ostree that should be integrated into apt-ostree. These commands are marked with `RPM_OSTREE_BUILTIN_FLAG_HIDDEN` and are essential for development, testing, and debugging purposes. + +## Commands Analysis + +### 1. testutils Command + +**Purpose**: Development debugging tool for testing and development workflows. + +**Flags**: `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD | RPM_OSTREE_BUILTIN_FLAG_HIDDEN` + +**Subcommands**: +- `inject-pkglist` - Inject package list metadata into OSTree commits +- `script-shell` - Run scripts in bubblewrap containers +- `generate-synthetic-upgrade` - Generate synthetic OS updates by modifying ELF files +- `integration-read-only` - Run integration tests on booted machine +- `c-units` - Run C unit tests +- `moo` - Test command for development verification + +**Implementation Details**: + +#### C++ Side (rpmostree-builtin-testutils.cxx) +```cpp +// inject-pkglist: Creates new commit with pkglist metadata +// - Reads existing commit +// - Creates RPM database package list +// - Writes new commit with pkglist metadata +// - Updates ref to point to new commit + +// script-shell: Runs scripts in isolated containers +// - Uses bubblewrap for containerization +// - Mounts root filesystem +// - Executes test scripts safely +``` + +#### Rust Side (testutils.rs) +```rust +// generate-synthetic-upgrade: Modifies ELF binaries +// - Finds ELF files in system directories +// - Mutates specified percentage of binaries +// - Creates new OSTree commit with modified files +// - Useful for testing upgrade paths + +// integration-read-only: Validates system state +// - Tests status JSON parsing +// - Validates package variants +// - Ensures client bindings work correctly +``` + +**Integration Plan for apt-ostree**: +1. Create `src/commands/testutils.rs` module +2. Implement all subcommands with APT equivalents +3. Add to CLI with hidden flag +4. Integrate with existing command structure + +### 2. shlib-backend Command + +**Purpose**: Shared library backend for IPC operations and package management. + +**Flags**: `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD | RPM_OSTREE_BUILTIN_FLAG_HIDDEN` + +**Subcommands**: +- `get-basearch` - Get base architecture +- `varsubst-basearch` - Variable substitution for architecture +- `packagelist-from-commit` - Extract package list from OSTree commit + +**Implementation Details**: +```cpp +// IPC-based communication using Unix domain sockets +// - Creates sealed memfd for data transfer +// - Uses DNF context for package operations +// - Integrates with OSTree repository operations +// - Handles package list extraction and formatting +``` + +**Integration Plan for apt-ostree**: +1. Create `src/commands/shlib_backend.rs` module +2. Replace DNF with APT equivalents +3. Implement IPC communication layer +4. Add architecture detection and variable substitution +5. Integrate with OSTree operations + +### 3. internals Command + +**Purpose**: Internal system commands for advanced operations. + +**Status**: Referenced in header file but implementation not found in current rpm-ostree source. + +**Flags**: Not specified (likely `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD`) + +**Integration Plan for apt-ostree**: +1. Research if this command exists in newer rpm-ostree versions +2. If not implemented, consider what internal operations would be useful +3. Implement as placeholder for future development +4. Add to CLI with appropriate flags + +## Implementation Strategy + +### Phase 1: Core Infrastructure +1. **Command Structure**: Add hidden command support to CLI +2. **Flag System**: Implement `APT_OSTREE_BUILTIN_FLAG_HIDDEN` equivalent +3. **Module Organization**: Create development commands module + +### Phase 2: testutils Implementation +1. **inject-pkglist**: APT package list injection +2. **script-shell**: Bubblewrap container execution +3. **synthetic-upgrade**: ELF binary modification for testing +4. **integration-tests**: System validation and testing + +### Phase 3: shlib-backend Implementation +1. **IPC Layer**: Unix domain socket communication +2. **Package Operations**: APT-based package management +3. **Architecture Detection**: Debian architecture handling +4. **Variable Substitution**: APT-specific variable handling + +### Phase 4: Integration and Testing +1. **Command Registration**: Add to main command dispatch +2. **Hidden Flag Support**: Implement in CLI help system +3. **Testing Framework**: Integration with existing test suite +4. **Documentation**: Developer and testing guides + +## Technical Considerations + +### APT vs DNF Differences +- **Package Format**: DEB vs RPM +- **Database Structure**: APT cache vs DNF sack +- **Architecture Names**: Debian vs Red Hat conventions +- **Variable Substitution**: APT-specific variables + +### OSTree Integration +- **Package Metadata**: APT package list format +- **Commit Structure**: OSTree commit metadata +- **Repository Operations**: OSTree repo integration +- **Deployment Management**: System deployment handling + +### Security and Isolation +- **Bubblewrap**: Container execution for scripts +- **File Descriptors**: Secure IPC communication +- **Permission Handling**: Root and user operations +- **Resource Limits**: Memory and process constraints + +## File Structure + +``` +src/commands/ +โ”œโ”€โ”€ testutils.rs # Development testing utilities +โ”œโ”€โ”€ shlib_backend.rs # Shared library backend +โ””โ”€โ”€ internals.rs # Internal system commands (future) + +src/cli.rs # Add hidden command support +src/commands/mod.rs # Register development commands +``` + +## CLI Integration + +### Hidden Command Support +```rust +#[derive(Subcommand)] +pub enum Commands { + // ... existing commands ... + + /// Development and debugging tools (hidden) + #[command(hide = true)] + Testutils(TestutilsArgs), + + /// Shared library backend (hidden) + #[command(hide = true)] + ShlibBackend(ShlibBackendArgs), + + /// Internal system commands (hidden) + #[command(hide = true)] + Internals(InternalsArgs), +} +``` + +### Flag System +```rust +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct CommandFlags { + pub local_cmd: bool, + pub hidden: bool, + pub requires_root: bool, + pub container_capable: bool, + pub supports_pkg_installs: bool, +} +``` + +## Benefits of Integration + +### Development Workflow +1. **Testing**: Automated testing and validation +2. **Debugging**: Package list inspection and modification +3. **Integration**: System state validation +4. **Scripting**: Safe script execution in containers + +### Quality Assurance +1. **Package Management**: Validate APT integration +2. **OSTree Operations**: Test commit and deployment logic +3. **System Integration**: Verify daemon and client communication +4. **Error Handling**: Test edge cases and failure modes + +### Maintenance and Support +1. **Troubleshooting**: Debug package and deployment issues +2. **Development**: Rapid iteration and testing +3. **Documentation**: Generate system state reports +4. **Validation**: Ensure system consistency + +## Conclusion + +Integrating these development commands from rpm-ostree into apt-ostree will provide essential tools for development, testing, and debugging. The commands are designed to be hidden from normal users while providing powerful capabilities for developers and system administrators. + +The implementation should maintain the same logical structure and behavior as rpm-ostree while adapting to APT-specific package management and Debian system conventions. This will ensure that apt-ostree provides the same level of development support as the original rpm-ostree implementation. + +## Next Steps + +1. **Research**: Verify current rpm-ostree implementation status +2. **Design**: Create detailed implementation specifications +3. **Implementation**: Develop commands with proper testing +4. **Integration**: Add to CLI and command dispatch system +5. **Testing**: Validate functionality and performance +6. **Documentation**: Create developer and testing guides diff --git a/docs/apt-ostree-daemon-plan/development-commands-implementation.md b/docs/apt-ostree-daemon-plan/development-commands-implementation.md new file mode 100644 index 00000000..89e1fde0 --- /dev/null +++ b/docs/apt-ostree-daemon-plan/development-commands-implementation.md @@ -0,0 +1,687 @@ +# Development Commands Implementation Guide + +## Technical Implementation Details + +This document provides detailed technical specifications for implementing the missing development commands from rpm-ostree into apt-ostree. + +## 1. testutils Command Implementation + +### Command Structure +```rust +#[derive(Subcommand)] +pub enum TestutilsSubcommands { + /// Inject package list metadata into OSTree commits + InjectPkglist(InjectPkglistArgs), + + /// Run scripts in bubblewrap containers + ScriptShell(ScriptShellArgs), + + /// Generate synthetic OS updates by modifying ELF files + GenerateSyntheticUpgrade(GenerateSyntheticUpgradeArgs), + + /// Run integration tests on booted machine + IntegrationReadOnly, + + /// Run C unit tests + CUnits, + + /// Test command for development verification + Moo, +} +``` + +### Argument Structures +```rust +#[derive(Args)] +pub struct InjectPkglistArgs { + /// Repository path + pub repo: String, + + /// OSTree reference + pub refspec: String, +} + +#[derive(Args)] +pub struct ScriptShellArgs { + /// Root path for script execution + #[arg(default_value = "/")] + pub rootpath: String, +} + +#[derive(Args)] +pub struct GenerateSyntheticUpgradeArgs { + /// Repository path + #[arg(long)] + pub repo: String, + + /// Source reference + #[arg(long = "srcref")] + pub src_ref: Option, + + /// OSTree reference + #[arg(long = "ref")] + pub ostref: String, + + /// Percentage of binaries to modify + #[arg(long, default_value = "30")] + pub percentage: u32, + + /// Commit version + #[arg(long)] + pub commit_version: Option, +} +``` + +### Core Implementation Functions + +#### inject_pkglist +```rust +impl TestutilsCommand { + fn inject_pkglist(&self, args: &InjectPkglistArgs) -> AptOstreeResult<()> { + // 1. Parse refspec into remote and ref + let (remote, ref_name) = self.parse_refspec(&args.refspec)?; + + // 2. Open OSTree repository + let repo = OstreeRepo::open_at(AT_FDCWD, &args.repo)?; + + // 3. Resolve reference to commit + let checksum = repo.resolve_rev(&args.refspec, false)?; + + // 4. Load existing commit + let commit = repo.load_commit(&checksum)?; + + // 5. Check if pkglist already exists + if self.has_pkglist_metadata(&commit) { + println!("Refspec '{}' already has pkglist metadata; exiting.", args.refspec); + return Ok(()); + } + + // 6. Create APT package list + let pkglist = self.create_apt_pkglist_variant(&repo, &checksum)?; + + // 7. Create new commit with pkglist metadata + let new_meta = self.add_pkglist_to_metadata(&commit, &pkglist)?; + + // 8. Write new commit + let new_checksum = self.write_new_commit(&repo, &checksum, &new_meta)?; + + // 9. Update reference + repo.set_ref_immediate(&remote, &ref_name, &new_checksum)?; + + println!("{} => {}", args.refspec, new_checksum); + Ok(()) + } + + fn create_apt_pkglist_variant(&self, repo: &OstreeRepo, commit: &str) -> AptOstreeResult { + // Create APT package list from commit + // This replaces the RPM-specific logic with APT equivalents + let apt_manager = AptManager::new(); + let packages = apt_manager.get_packages_from_commit(repo, commit)?; + + // Convert to GVariant format compatible with OSTree + self.packages_to_gvariant(&packages) + } +} +``` + +#### script_shell +```rust +impl TestutilsCommand { + fn script_shell(&self, args: &ScriptShellArgs) -> AptOstreeResult<()> { + // 1. Open root filesystem directory + let rootfs_dfd = self.open_rootfs_dir(&args.rootpath)?; + + // 2. Run script in bubblewrap container + self.run_script_in_bwrap_container( + rootfs_dfd, + None, + true, + "testscript", + None, + None, + None, + None, + STDIN_FILENO, + ) + } + + fn run_script_in_bwrap_container( + &self, + rootfs_dfd: i32, + env: Option<&[String]>, + read_only: bool, + script_name: &str, + user: Option<&str>, + group: Option<&str>, + cwd: Option<&str>, + extra_args: Option<&[String]>, + stdin_fd: i32, + ) -> AptOstreeResult<()> { + // Implement bubblewrap container execution + // This provides safe script execution environment + let mut cmd = Command::new("bwrap"); + + // Add bubblewrap arguments for isolation + cmd.args(&[ + "--dev-bind", "/", "/", + "--proc", "/proc", + "--tmpfs", "/tmp", + ]); + + if read_only { + cmd.arg("--ro-bind"); + } + + // Execute script + cmd.arg("bash") + .arg("-c") + .arg(script_name) + .stdin(unsafe { std::os::unix::io::FromRawFd::from_raw_fd(stdin_fd) }); + + let status = cmd.status()?; + if !status.success() { + return Err(AptOstreeError::System("Script execution failed".to_string())); + } + + Ok(()) + } +} +``` + +#### generate_synthetic_upgrade +```rust +impl TestutilsCommand { + fn generate_synthetic_upgrade(&self, args: &GenerateSyntheticUpgradeArgs) -> AptOstreeResult<()> { + // 1. Remount sysroot as read-write + self.remount_sysroot_rw()?; + + // 2. Create temporary directory + let tempdir = tempfile::tempdir_in(Path::new(&args.repo).join("tmp"))?; + let tmp_rootfs = tempdir.path().join("rootfs"); + fs::create_dir(&tmp_rootfs)?; + + // 3. Create note file + let notepath = tempdir.path().join("note"); + fs::write(¬epath, "Synthetic upgrade")?; + + // 4. Check for objcopy availability + let have_objcopy = Path::new("/usr/bin/objcopy").exists(); + + // 5. Mutate executables + let mutated = self.mutate_executables( + &tmp_rootfs, + args.percentage, + ¬epath, + have_objcopy, + )?; + + // 6. Create new OSTree commit + self.create_synthetic_commit(&args.repo, &args.ostref, &tmp_rootfs, &args.src_ref)?; + + println!("Mutated ELF files: {}", mutated); + Ok(()) + } + + fn mutate_executables( + &self, + dest: &Path, + percentage: u32, + notepath: &Path, + have_objcopy: bool, + ) -> AptOstreeResult { + let mut mutated = 0; + let binary_dirs = &["usr/bin", "usr/lib", "usr/lib64"]; + + for binary_dir in binary_dirs { + let src_path = Path::new("/").join(binary_dir); + if src_path.exists() { + let dest_path = dest.join(binary_dir); + fs::create_dir_all(&dest_path)?; + + mutated += self.mutate_executables_in_dir( + &src_path, + &dest_path, + percentage, + notepath, + have_objcopy, + )?; + } + } + + Ok(mutated) + } + + fn mutate_executables_in_dir( + &self, + src: &Path, + dest: &Path, + percentage: u32, + notepath: &Path, + have_objcopy: bool, + ) -> AptOstreeResult { + let mut mutated = 0; + + for entry in fs::read_dir(src)? { + let entry = entry?; + let path = entry.path(); + + if path.is_file() && self.is_elf_executable(&path)? { + if self.should_mutate(percentage) { + self.mutate_one_executable(&path, dest, notepath, have_objcopy)?; + mutated += 1; + } + } + } + + Ok(mutated) + } + + fn is_elf_executable(&self, path: &Path) -> AptOstreeResult { + let mut file = fs::File::open(path)?; + let mut buf = [0; 5]; + + file.read_exact(&mut buf)?; + + Ok(buf[0] == 0x7F && &buf[1..4] == b"ELF") + } + + fn should_mutate(&self, percentage: u32) -> bool { + let mut rng = rand::thread_rng(); + rng.gen_range(1..=100) <= percentage + } +} +``` + +## 2. shlib-backend Command Implementation + +### Command Structure +```rust +#[derive(Subcommand)] +pub enum ShlibBackendSubcommands { + /// Get base architecture + GetBasearch, + + /// Variable substitution for architecture + VarsubstBasearch { + /// Source string for substitution + source: String, + }, + + /// Extract package list from OSTree commit + PackagelistFromCommit { + /// Commit hash + commit: String, + }, +} +``` + +### Core Implementation +```rust +impl ShlibBackendCommand { + fn handle_subcommand(&self, subcommand: &ShlibBackendSubcommands) -> AptOstreeResult<()> { + // 1. Create IPC socket + let ipc_sock = self.create_ipc_socket()?; + + // 2. Handle subcommand + let result = match subcommand { + ShlibBackendSubcommands::GetBasearch => self.get_basearch(), + ShlibBackendSubcommands::VarsubstBasearch { source } => { + self.varsubst_basearch(source) + } + ShlibBackendSubcommands::PackagelistFromCommit { commit } => { + self.packagelist_from_commit(commit) + } + }?; + + // 3. Send result via IPC + self.send_memfd_result(&ipc_sock, result)?; + + Ok(()) + } + + fn get_basearch(&self) -> AptOstreeResult { + // Get base architecture using APT + let apt_manager = AptManager::new(); + let arch = apt_manager.get_base_architecture()?; + + Ok(GVariant::new_string(arch)) + } + + fn varsubst_basearch(&self, source: &str) -> AptOstreeResult { + // Get APT variable substitutions + let apt_manager = AptManager::new(); + let varsubsts = apt_manager.get_variable_substitutions()?; + + // Perform variable substitution + let result = self.substitute_variables(source, &varsubsts)?; + + Ok(GVariant::new_string(result)) + } + + fn packagelist_from_commit(&self, commit: &str) -> AptOstreeResult { + // 1. Open OSTree repository + let repo = OstreeRepo::open_at(AT_FDCWD, ".")?; + + // 2. Get package list from commit + let packages = self.get_packages_from_commit(&repo, commit)?; + + // 3. Convert to GVariant format + let pkglist = self.packages_to_gvariant(&packages)?; + + Ok(GVariant::new_maybe( + "aptostree.shlib.ipc.pkglist", + Some(&pkglist), + )) + } + + fn create_ipc_socket(&self) -> AptOstreeResult { + // Create IPC socket using file descriptor + let fd = std::env::var("APT_OSTREE_SHLIB_IPC_FD") + .ok() + .and_then(|s| s.parse::().ok()) + .ok_or_else(|| { + AptOstreeError::System("APT_OSTREE_SHLIB_IPC_FD environment variable not set".to_string()) + })?; + + GSocket::new_from_fd(fd) + } + + fn send_memfd_result(&self, ipc_sock: &GSocket, data: GVariant) -> AptOstreeResult<()> { + // 1. Create sealed memfd + let memfd = self.create_sealed_memfd("apt-ostree-shlib-backend", &data)?; + + // 2. Send via Unix domain socket + let fdarray = [memfd, -1]; + let list = GUnixFDList::new_from_array(&fdarray, 1); + let message = GUnixFDMessage::new_with_fd_list(&list); + + let buffer = [0xFF]; + let ov = GOutputVector { + buffer: &buffer, + size: buffer.len(), + }; + + let sent = ipc_sock.send_message( + None, + &[ov], + &[&message], + GSocketMsgFlags::NONE, + )?; + + if sent != 1 { + return Err(AptOstreeError::System("Failed to send IPC message".to_string())); + } + + Ok(()) + } +} +``` + +## 3. internals Command Implementation + +### Command Structure +```rust +#[derive(Subcommand)] +pub enum InternalsSubcommands { + /// Internal system diagnostics + Diagnostics, + + /// System state validation + ValidateState, + + /// Debug information dump + DebugDump, +} +``` + +### Core Implementation +```rust +impl InternalsCommand { + fn handle_subcommand(&self, subcommand: &InternalsSubcommands) -> AptOstreeResult<()> { + match subcommand { + InternalsSubcommands::Diagnostics => self.run_diagnostics(), + InternalsSubcommands::ValidateState => self.validate_system_state(), + InternalsSubcommands::DebugDump => self.dump_debug_info(), + } + } + + fn run_diagnostics(&self) -> AptOstreeResult<()> { + println!("๐Ÿ” Running Internal Diagnostics"); + println!("==============================="); + + // Check system components + self.check_ostree_system()?; + self.check_apt_system()?; + self.check_daemon_status()?; + self.check_file_permissions()?; + + println!("Diagnostics completed successfully"); + Ok(()) + } + + fn validate_system_state(&self) -> AptOstreeResult<()> { + println!("โœ… Validating System State"); + println!("==========================="); + + // Validate OSTree state + let ostree_manager = OstreeManager::new(); + if ostree_manager.is_available() { + println!("OSTree: Available"); + self.validate_ostree_state(&ostree_manager)?; + } else { + println!("OSTree: Not available"); + } + + // Validate APT state + let apt_manager = AptManager::new(); + self.validate_apt_state(&apt_manager)?; + + println!("System state validation completed"); + Ok(()) + } + + fn dump_debug_info(&self) -> AptOstreeResult<()> { + println!("๐Ÿ› Debug Information Dump"); + println!("========================="); + + // System information + self.dump_system_info()?; + + // OSTree information + self.dump_ostree_info()?; + + // APT information + self.dump_apt_info()?; + + // Daemon information + self.dump_daemon_info()?; + + println!("Debug information dump completed"); + Ok(()) + } +} +``` + +## 4. CLI Integration + +### Hidden Command Support +```rust +// Add to src/cli.rs +#[derive(Subcommand)] +pub enum Commands { + // ... existing commands ... + + /// Development and debugging tools (hidden) + #[command(hide = true)] + Testutils(TestutilsArgs), + + /// Shared library backend (hidden) + #[command(hide = true)] + ShlibBackend(ShlibBackendArgs), + + /// Internal system commands (hidden) + #[command(hide = true)] + Internals(InternalsArgs), +} + +#[derive(Args)] +pub struct TestutilsArgs { + #[command(subcommand)] + pub subcommand: TestutilsSubcommands, +} + +#[derive(Args)] +pub struct ShlibBackendArgs { + #[command(subcommand)] + pub subcommand: ShlibBackendSubcommands, +} + +#[derive(Args)] +pub struct InternalsArgs { + #[command(subcommand)] + pub subcommand: InternalsSubcommands, +} +``` + +### Command Registration +```rust +// Add to src/commands/mod.rs +pub mod testutils; +pub mod shlib_backend; +pub mod internals; + +// In register_commands function +self.register(Box::new(testutils::TestutilsCommand::new())); +self.register(Box::new(shlib_backend::ShlibBackendCommand::new())); +self.register(Box::new(internals::InternalsCommand::new())); +``` + +### Main Dispatch +```rust +// Add to src/main.rs match statement +cli::Commands::Testutils(args) => { + let args_vec = vec!["testutils".to_string()]; + commands::testutils::TestutilsCommand::new().execute(&args_vec) +}, +cli::Commands::ShlibBackend(args) => { + let args_vec = vec!["shlib-backend".to_string()]; + commands::shlib_backend::ShlibBackendCommand::new().execute(&args_vec) +}, +cli::Commands::Internals(args) => { + let args_vec = vec!["internals".to_string()]; + commands::internals::InternalsCommand::new().execute(&args_vec) +}, +``` + +## 5. Dependencies and Features + +### Cargo.toml Additions +```toml +[dependencies] +# For bubblewrap integration +bubblewrap = "0.1" +# For ELF file manipulation +goblin = "0.8" +# For random number generation +rand = "0.8" +# For temporary directories +tempfile = "3.0" +# For file operations +cap-std = "1.0" +cap-std-ext = "1.0" +# For system calls +libc = "0.2" +``` + +### Feature Flags +```toml +[features] +# Development commands (hidden by default) +development = ["bubblewrap", "goblin", "rand", "tempfile"] +# Full development support +dev-full = ["development", "cap-std", "cap-std-ext"] +``` + +## 6. Testing and Validation + +### Unit Tests +```rust +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_inject_pkglist() { + // Test package list injection + } + + #[test] + fn test_script_shell() { + // Test script execution + } + + #[test] + fn test_synthetic_upgrade() { + // Test synthetic upgrade generation + } + + #[test] + fn test_shlib_backend() { + // Test shared library backend + } + + #[test] + fn test_internals() { + // Test internal commands + } +} +``` + +### Integration Tests +```rust +#[cfg(test)] +mod integration_tests { + use super::*; + + #[test] + fn test_full_development_workflow() { + // Test complete development workflow + } + + #[test] + fn test_debugging_tools() { + // Test debugging capabilities + } + + #[test] + fn test_system_validation() { + // Test system validation tools + } +} +``` + +## 7. Security Considerations + +### Bubblewrap Integration +- **Isolation**: Scripts run in isolated containers +- **Resource Limits**: Memory and process constraints +- **File Access**: Controlled filesystem access +- **Network Access**: Restricted network access + +### IPC Security +- **File Descriptors**: Secure descriptor passing +- **Memory Protection**: Sealed memfd for data transfer +- **Access Control**: Proper permission checking +- **Input Validation**: Validate all IPC inputs + +### Package Operations +- **Signature Verification**: Verify package signatures +- **Repository Validation**: Validate repository sources +- **Permission Checking**: Check operation permissions +- **Audit Logging**: Log all package operations + +## Conclusion + +This implementation guide provides comprehensive technical specifications for integrating the missing development commands from rpm-ostree into apt-ostree. The commands maintain the same logical structure and behavior while adapting to APT-specific package management and Debian system conventions. + +The implementation includes proper security measures, comprehensive testing, and integration with the existing apt-ostree architecture. These development tools will significantly enhance the development, testing, and debugging capabilities of apt-ostree. diff --git a/docs/apt-ostree-daemon-plan/development-commands-summary.md b/docs/apt-ostree-daemon-plan/development-commands-summary.md new file mode 100644 index 00000000..5c63e909 --- /dev/null +++ b/docs/apt-ostree-daemon-plan/development-commands-summary.md @@ -0,0 +1,236 @@ +# Development Commands Integration Summary + +## Executive Summary + +This document summarizes the plan to integrate the missing development and debugging commands from rpm-ostree into apt-ostree. These commands are essential for development, testing, and debugging workflows and will significantly enhance the development capabilities of apt-ostree. + +## Missing Commands Overview + +### 1. testutils Command +- **Purpose**: Development debugging tool for testing and development workflows +- **Status**: Fully implemented in rpm-ostree (C++ and Rust) +- **Priority**: High - Essential for development and testing +- **Complexity**: Medium - Requires APT integration and OSTree operations + +### 2. shlib-backend Command +- **Purpose**: Shared library backend for IPC operations and package management +- **Status**: Fully implemented in rpm-ostree (C++) +- **Priority**: High - Essential for package operations and IPC +- **Complexity**: High - Requires IPC layer and APT integration + +### 3. internals Command +- **Purpose**: Internal system commands for advanced operations +- **Status**: Referenced in header but implementation not found +- **Priority**: Medium - Useful for system diagnostics +- **Complexity**: Low - Can be implemented as placeholder + +## Implementation Benefits + +### Development Workflow Enhancement +1. **Automated Testing**: Generate synthetic upgrades for testing +2. **Package Management**: Debug package list and metadata issues +3. **System Validation**: Validate system state and configuration +4. **Script Execution**: Safe script execution in isolated containers + +### Quality Assurance +1. **Package Integration**: Validate APT and OSTree integration +2. **System Consistency**: Ensure system state consistency +3. **Error Handling**: Test edge cases and failure modes +4. **Performance Testing**: Benchmark system operations + +### Maintenance and Support +1. **Troubleshooting**: Debug deployment and package issues +2. **Development**: Rapid iteration and testing capabilities +3. **Documentation**: Generate system state reports +4. **Validation**: Ensure system integrity + +## Technical Implementation Plan + +### Phase 1: Core Infrastructure (Week 1-2) +- [ ] Add hidden command support to CLI +- [ ] Implement command flag system +- [ ] Create development commands module structure +- [ ] Add command registration and dispatch + +### Phase 2: testutils Implementation (Week 3-4) +- [ ] Implement `inject-pkglist` with APT integration +- [ ] Implement `script-shell` with bubblewrap +- [ ] Implement `generate-synthetic-upgrade` for testing +- [ ] Implement `integration-read-only` validation +- [ ] Add unit and integration tests + +### Phase 3: shlib-backend Implementation (Week 5-6) +- [ ] Implement IPC communication layer +- [ ] Implement APT-based package operations +- [ ] Implement architecture detection +- [ ] Implement variable substitution +- [ ] Add security and validation + +### Phase 4: Integration and Testing (Week 7-8) +- [ ] Integrate all commands into main system +- [ ] Add comprehensive testing framework +- [ ] Implement security measures +- [ ] Create documentation and examples +- [ ] Performance optimization + +## Dependencies and Requirements + +### New Dependencies +```toml +[dependencies] +bubblewrap = "0.1" # Container isolation +goblin = "0.8" # ELF file manipulation +rand = "0.8" # Random number generation +tempfile = "3.0" # Temporary directory management +cap-std = "1.0" # Capability-based file operations +cap-std-ext = "1.0" # Extended capability operations +``` + +### System Requirements +- **bubblewrap**: For script containerization +- **objcopy**: For ELF binary modification (optional) +- **OSTree**: For repository operations +- **APT**: For package management operations + +### Feature Flags +```toml +[features] +development = ["bubblewrap", "goblin", "rand", "tempfile"] +dev-full = ["development", "cap-std", "cap-std-ext"] +``` + +## Security Considerations + +### Container Isolation +- **Bubblewrap**: Secure script execution environment +- **Resource Limits**: Memory and process constraints +- **File Access**: Controlled filesystem access +- **Network Access**: Restricted network access + +### IPC Security +- **File Descriptors**: Secure descriptor passing +- **Memory Protection**: Sealed memfd for data transfer +- **Access Control**: Proper permission checking +- **Input Validation**: Validate all IPC inputs + +### Package Operations +- **Signature Verification**: Verify package signatures +- **Repository Validation**: Validate repository sources +- **Permission Checking**: Check operation permissions +- **Audit Logging**: Log all package operations + +## Testing Strategy + +### Unit Testing +- **Command Logic**: Test individual command functionality +- **Error Handling**: Test error conditions and edge cases +- **Input Validation**: Test argument parsing and validation +- **Mock Integration**: Test with mocked dependencies + +### Integration Testing +- **System Integration**: Test with real OSTree and APT systems +- **Command Interaction**: Test command combinations and workflows +- **Performance Testing**: Benchmark command execution times +- **Security Testing**: Validate security measures and isolation + +### End-to-End Testing +- **Development Workflow**: Test complete development scenarios +- **Debugging Tools**: Test debugging and troubleshooting capabilities +- **System Validation**: Test system state validation tools +- **Error Recovery**: Test error handling and recovery mechanisms + +## Documentation Requirements + +### Developer Documentation +- **Command Reference**: Complete command documentation +- **API Reference**: Internal API documentation +- **Examples**: Usage examples and common scenarios +- **Troubleshooting**: Common issues and solutions + +### User Documentation +- **Installation Guide**: Setup and configuration +- **Usage Guide**: Basic usage and common commands +- **Configuration**: Configuration options and settings +- **Security Guide**: Security considerations and best practices + +### Integration Documentation +- **Architecture**: System architecture and design +- **Integration Guide**: Integration with existing systems +- **API Integration**: External API usage and integration +- **Deployment Guide**: Deployment and operational considerations + +## Risk Assessment + +### Technical Risks +- **Complexity**: IPC and containerization complexity +- **Integration**: APT and OSTree integration challenges +- **Performance**: Impact on system performance +- **Security**: Security vulnerabilities in new features + +### Mitigation Strategies +- **Incremental Development**: Implement features incrementally +- **Comprehensive Testing**: Extensive testing at all levels +- **Security Review**: Regular security reviews and audits +- **Performance Monitoring**: Continuous performance monitoring + +### Dependencies +- **External Tools**: Dependence on bubblewrap and other tools +- **System Requirements**: OSTree and APT system requirements +- **Platform Support**: Debian-specific implementation +- **Maintenance**: Ongoing maintenance and updates + +## Success Metrics + +### Development Efficiency +- **Testing Speed**: Reduced time for testing and validation +- **Debugging Speed**: Faster issue identification and resolution +- **Development Cycle**: Reduced development iteration time +- **Code Quality**: Improved code quality and reliability + +### System Reliability +- **Error Detection**: Better error detection and reporting +- **System Validation**: Improved system state validation +- **Issue Resolution**: Faster issue resolution and recovery +- **System Stability**: Improved overall system stability + +### User Experience +- **Developer Tools**: Enhanced development and debugging tools +- **System Management**: Better system management capabilities +- **Troubleshooting**: Improved troubleshooting and support +- **Documentation**: Better documentation and examples + +## Conclusion + +Integrating the missing development commands from rpm-ostree into apt-ostree will provide essential tools for development, testing, and debugging. These commands will significantly enhance the development capabilities of apt-ostree while maintaining the same logical structure and behavior as the original rpm-ostree implementation. + +The implementation plan provides a structured approach to development with clear phases, comprehensive testing, and proper security measures. The benefits include improved development workflow, enhanced quality assurance, and better maintenance and support capabilities. + +## Next Steps + +1. **Immediate Actions**: + - Review and approve implementation plan + - Set up development environment + - Begin Phase 1 implementation + +2. **Short Term (1-2 weeks)**: + - Complete core infrastructure + - Begin testutils implementation + - Set up testing framework + +3. **Medium Term (3-6 weeks)**: + - Complete testutils implementation + - Implement shlib-backend + - Begin integration testing + +4. **Long Term (7-8 weeks)**: + - Complete integration and testing + - Performance optimization + - Documentation and deployment + +## Contact and Support + +For questions or support regarding this implementation plan, please refer to: +- **Technical Documentation**: `/docs/apt-ostree-daemon-plan/` +- **Implementation Guide**: `development-commands-implementation.md` +- **Analysis Document**: `development-commands-analysis.md` +- **Project Repository**: `/opt/Projects/apt-ostree/` diff --git a/docs/apt-ostree-daemon-plan/documentation/documentation-plan.md b/docs/apt-ostree-daemon-plan/documentation/documentation-plan.md index 336a1120..bbe2149a 100644 --- a/docs/apt-ostree-daemon-plan/documentation/documentation-plan.md +++ b/docs/apt-ostree-daemon-plan/documentation/documentation-plan.md @@ -422,7 +422,7 @@ src/ ## System Requirements ### Supported Distributions -- Debian 13+ (Bookworm) +- Debian 13+ (Trixie) - Ubuntu 25.04+ (Noble Numbat) ### Hardware Requirements diff --git a/docs/apt-ostree-daemon-plan/implementation/deployment-guide.md b/docs/apt-ostree-daemon-plan/implementation/deployment-guide.md index 551f79b1..536796b5 100644 --- a/docs/apt-ostree-daemon-plan/implementation/deployment-guide.md +++ b/docs/apt-ostree-daemon-plan/implementation/deployment-guide.md @@ -59,7 +59,7 @@ sudo apt install -y \ ```bash # Add apt-ostree repository echo "deb [signed-by=/usr/share/keyrings/apt-ostree-archive-keyring.gpg] \ - https://apt.ostree.dev/debian bookworm main" | \ + https://apt.ostree.dev/debian trixie main" | \ sudo tee /etc/apt/sources.list.d/apt-ostree.list # Add repository key diff --git a/docs/apt-ostree-daemon-plan/implementation/testing-strategy.md b/docs/apt-ostree-daemon-plan/implementation/testing-strategy.md index 0a1bbc0b..3e8a122d 100644 --- a/docs/apt-ostree-daemon-plan/implementation/testing-strategy.md +++ b/docs/apt-ostree-daemon-plan/implementation/testing-strategy.md @@ -274,7 +274,6 @@ async fn test_apt_database_operations() { let deps = manager.resolve_dependencies(&vec!["vim".to_string()]).await.unwrap(); assert!(!deps.is_empty()); } -``` #### **OSTree Repository Operations** ```rust @@ -565,7 +564,7 @@ jobs: #### **Docker Test Environment** ```dockerfile # tests/Dockerfile.test -FROM debian:bookworm-slim +FROM debian:trixie-slim # Install system dependencies RUN apt-get update && apt-get install -y \ @@ -738,7 +737,7 @@ Installed: (none) Candidate: 2:9.0.1378-1 Version table: *** 2:9.0.1378-1 500 - 500 http://deb.debian.org/debian bookworm/main amd64 Packages + 500 http://deb.debian.org/debian trixie/main amd64 Packages 100 /var/lib/dpkg/status "#; ``` diff --git a/docs/cli-parity-checklist.md b/docs/cli-parity-checklist.md new file mode 100644 index 00000000..9dfead18 --- /dev/null +++ b/docs/cli-parity-checklist.md @@ -0,0 +1,101 @@ +## CLI Parity Checklist (apt-ostree vs rpm-ostree) + +Source references: +- rpm-ostree builtins: `inspiration/rpm-ostree/src/app/` (files named `rpmostree-builtin-*.cxx` and related `*-builtins*`) +- apt-ostree CLI: `src/cli.rs` + +### rpm-ostree top-level commands detected +- status +- upgrade +- rollback +- deploy +- rebase +- initramfs +- initramfs-etc +- kargs +- reload +- cancel +- reset +- refresh-md +- compose +- override +- apply-live +- finalize-deployment +- cleanup +- start-daemon +- db +- ex (group) +- testutils (hidden) +- shlib-backend (hidden) + +### apt-ostree top-level commands (src/cli.rs) +- Status +- Upgrade +- Rollback +- Deploy +- Rebase +- Install +- Uninstall +- Search +- Initramfs +- InitramfsEtc +- Kargs +- Reload +- Cancel +- Transaction (group) +- Compose (group) +- Db (group) +- Override (group) +- Reset +- RefreshMd +- ApplyLive +- Usroverlay +- Cleanup +- FinalizeDeployment +- Metrics +- StartDaemon +- Ex (group) +- Countme +- Container (group) +- Testutils (hidden) +- ShlibBackend (hidden) +- Internals (hidden) + +### Parity status +- status: present (Status) +- upgrade: present (Upgrade) +- rollback: present (Rollback) +- deploy: present (Deploy) +- rebase: present (Rebase) +- initramfs: present (Initramfs) +- initramfs-etc: present (InitramfsEtc) +- kargs: present (Kargs) +- reload: present (Reload) +- cancel: present (Cancel) +- reset: present (Reset) +- refresh-md: present (RefreshMd) +- compose: present (Compose) +- override: present (Override) +- apply-live: present (ApplyLive) +- finalize-deployment: present (FinalizeDeployment) +- cleanup: present (Cleanup) +- start-daemon: present (StartDaemon) +- db: present (Db) +- ex: present (Ex) +- testutils (hidden): present (Testutils) +- shlib-backend (hidden): present (ShlibBackend) + +### Differences and extras +- install/uninstall: present in apt-ostree; maps to rpm-ostree package layering builtins (expected) +- search: present in apt-ostree; rpm-ostree has `db search` flows (OK) +- transaction (group): apt-ostree adds management helpers; aligns with rpm-ostree transaction concepts +- usroverlay: extra in apt-ostree (not a top-level in rpm-ostree; keep as experimental) +- metrics: extra in apt-ostree (telemetry; not in rpm-ostree) +- countme: extra in apt-ostree (dnf concept; not in rpm-ostree) +- container (group): extra in apt-ostree (rpm-ostree has container helpers but not a top-level group) +- internals (hidden): extra diagnostics; acceptable as hidden + +### Next actions for strict parity +- Review and align flags/options per command against rpm-ostree +- Ensure help text and defaults match where applicable +- Gate non-parity extras (`usroverlay`, `metrics`, `countme`, `container`) behind experimental or hidden flags if needed diff --git a/docs/developer-guide.md b/docs/developer-guide.md new file mode 100644 index 00000000..46848563 --- /dev/null +++ b/docs/developer-guide.md @@ -0,0 +1,623 @@ +# apt-ostree Developer Guide + +## Table of Contents +1. [Architecture Overview](#architecture-overview) +2. [Development Setup](#development-setup) +3. [Code Organization](#code-organization) +4. [API Documentation](#api-documentation) +5. [Development Workflow](#development-workflow) +6. [Testing and Debugging](#testing-and-debugging) +7. [Contributing Guidelines](#contributing-guidelines) + +## Architecture Overview + +### System Components +apt-ostree consists of several key components: + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ CLI Client โ”‚ โ”‚ System Daemon โ”‚ โ”‚ OSTree Repo โ”‚ +โ”‚ (apt-ostree) โ”‚โ—„โ”€โ”€โ–บโ”‚ (apt-ostreed) โ”‚โ—„โ”€โ”€โ–บโ”‚ (/ostree/) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ โ”‚ โ”‚ + โ”‚ โ”‚ โ”‚ + โ–ผ โ–ผ โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ APT System โ”‚ โ”‚ D-Bus Layer โ”‚ โ”‚ File System โ”‚ +โ”‚ (Package Mgmt)โ”‚ โ”‚ (IPC Interface) โ”‚ โ”‚ (Deployments) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Component Responsibilities + +#### CLI Client (apt-ostree) +- **Command parsing**: Uses `clap` for argument parsing +- **User interface**: Provides user-friendly command interface +- **Command dispatch**: Routes commands to appropriate handlers +- **Output formatting**: Formats results for user consumption + +#### System Daemon (apt-ostreed) +- **Background processing**: Handles long-running operations +- **D-Bus interface**: Provides IPC for system operations +- **Transaction management**: Manages atomic system changes +- **Security**: Implements Polkit authentication + +#### OSTree Integration +- **Repository management**: Manages OSTree repositories +- **Deployment handling**: Handles system deployments +- **Atomic operations**: Ensures system consistency +- **Rollback support**: Provides system recovery + +#### APT Integration +- **Package resolution**: Resolves package dependencies +- **Repository management**: Manages APT repositories +- **Transaction handling**: Handles package transactions +- **Conflict resolution**: Resolves package conflicts + +## Development Setup + +### Prerequisites +- **Rust toolchain**: Rust 1.75+ with Cargo +- **System dependencies**: See installation guide +- **Development tools**: Git, make, pkg-config +- **Documentation tools**: rustdoc, cargo-doc + +### Environment Setup +```bash +# Clone repository +git clone https://github.com/robojerk/apt-ostree.git +cd apt-ostree + +# Install Rust toolchain +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +source ~/.cargo/env + +# Install system dependencies +sudo apt-get install build-essential pkg-config \ + libostree-dev libapt-pkg-dev libpolkit-gobject-1-dev \ + libdbus-1-dev libsystemd-dev + +# Install development tools +cargo install cargo-outdated cargo-audit cargo-tarpaulin +``` + +### Build Configuration +```bash +# Development build with all features +cargo build --features development,dev-full + +# Release build +cargo build --release + +# Documentation +cargo doc --open --features development + +# Run tests +cargo test --features development +``` + +## Code Organization + +### Directory Structure +``` +src/ +โ”œโ”€โ”€ main.rs # CLI entry point +โ”œโ”€โ”€ cli.rs # Command-line interface definitions +โ”œโ”€โ”€ commands/ # Command implementations +โ”‚ โ”œโ”€โ”€ mod.rs # Command registry +โ”‚ โ”œโ”€โ”€ package.rs # Package management commands +โ”‚ โ”œโ”€โ”€ system.rs # System management commands +โ”‚ โ”œโ”€โ”€ testutils.rs # Development utilities +โ”‚ โ”œโ”€โ”€ shlib_backend.rs # Shared library backend +โ”‚ โ””โ”€โ”€ internals.rs # Internal diagnostics +โ”œโ”€โ”€ lib/ # Core library code +โ”‚ โ”œโ”€โ”€ mod.rs # Library entry point +โ”‚ โ”œโ”€โ”€ apt.rs # APT integration +โ”‚ โ”œโ”€โ”€ ostree.rs # OSTree integration +โ”‚ โ”œโ”€โ”€ security.rs # Security and authentication +โ”‚ โ”œโ”€โ”€ system.rs # System operations +โ”‚ โ”œโ”€โ”€ transaction.rs # Transaction management +โ”‚ โ””โ”€โ”€ logging.rs # Logging and metrics +โ”œโ”€โ”€ daemon/ # Daemon implementation +โ”‚ โ”œโ”€โ”€ main.rs # Daemon entry point +โ”‚ โ”œโ”€โ”€ dbus.rs # D-Bus interface +โ”‚ โ”œโ”€โ”€ polkit.rs # Polkit integration +โ”‚ โ””โ”€โ”€ systemd.rs # systemd integration +โ””โ”€โ”€ tests/ # Test suite + โ”œโ”€โ”€ integration_tests.rs + โ””โ”€โ”€ common/ +``` + +### Key Modules + +#### Command System +The command system uses a trait-based approach for extensibility: + +```rust +pub trait Command { + fn execute(&self, args: &[String]) -> Result<(), Box>; + fn help(&self) -> String; + fn usage(&self) -> String; +} + +pub struct CommandRegistry { + commands: HashMap>, +} +``` + +#### Library Interface +The library provides a clean API for external consumers: + +```rust +pub struct AptOstree { + apt_manager: AptManager, + ostree_manager: OstreeManager, + security_manager: SecurityManager, +} + +impl AptOstree { + pub fn new() -> Result { /* ... */ } + pub fn install_packages(&self, packages: &[String]) -> Result<(), Error> { /* ... */ } + pub fn remove_packages(&self, packages: &[String]) -> Result<(), Error> { /* ... */ } +} +``` + +## API Documentation + +### Core Types + +#### Package Management +```rust +pub struct Package { + pub name: String, + pub version: String, + pub architecture: String, + pub dependencies: Vec, + pub conflicts: Vec, +} + +pub struct PackageTransaction { + pub packages: Vec, + pub operation: TransactionOperation, + pub status: TransactionStatus, +} +``` + +#### OSTree Integration +```rust +pub struct Deployment { + pub id: String, + pub branch: String, + pub commit: String, + pub timestamp: DateTime, + pub packages: Vec, +} + +pub struct OSTreeRepository { + pub path: PathBuf, + pub mode: RepositoryMode, + pub remotes: HashMap, +} +``` + +#### Security +```rust +pub struct SecurityContext { + pub user: String, + pub groups: Vec, + pub permissions: Permissions, +} + +pub struct AuthenticationResult { + pub authenticated: bool, + pub user: Option, + pub permissions: Permissions, +} +``` + +### Public API + +#### High-Level Operations +```rust +impl AptOstree { + /// Install packages atomically + pub fn install_packages(&self, packages: &[String]) -> Result<(), Error> + + /// Remove packages atomically + pub fn remove_packages(&self, packages: &[String]) -> Result<(), Error> + + /// Upgrade all packages + pub fn upgrade_system(&self) -> Result<(), Error> + + /// Rollback to previous deployment + pub fn rollback(&self) -> Result<(), Error> +} +``` + +#### Transaction Management +```rust +impl TransactionManager { + /// Start a new transaction + pub fn start_transaction(&mut self, operation: TransactionOperation) -> Result + + /// Add packages to transaction + pub fn add_packages(&mut self, transaction_id: TransactionId, packages: &[String]) -> Result<(), Error> + + /// Commit transaction + pub fn commit_transaction(&mut self, transaction_id: TransactionId) -> Result<(), Error> + + /// Rollback transaction + pub fn rollback_transaction(&mut self, transaction_id: TransactionId) -> Result<(), Error> +} +``` + +#### System Operations +```rust +impl SystemManager { + /// Get system status + pub fn get_system_status(&self) -> SystemStatus + + /// Manage kernel arguments + pub fn set_kernel_args(&self, args: &[String]) -> Result<(), Error> + + /// Regenerate initramfs + pub fn regenerate_initramfs(&self) -> Result<(), Error> +} +``` + +## Development Workflow + +### Adding New Commands + +#### 1. Define Command Structure +```rust +// src/cli.rs +#[derive(Subcommand)] +pub enum Commands { + // ... existing commands ... + NewCommand(NewCommandArgs), +} + +#[derive(Args)] +pub struct NewCommandArgs { + #[arg(long)] + option: Option, + + #[arg(value_name = "TARGET")] + target: String, +} +``` + +#### 2. Implement Command Logic +```rust +// src/commands/new_command.rs +pub struct NewCommand; + +impl Command for NewCommand { + fn execute(&self, args: &[String]) -> Result<(), Box> { + // Implementation here + Ok(()) + } + + fn help(&self) -> String { + "Help text for new command".to_string() + } + + fn usage(&self) -> String { + "new-command [OPTIONS] TARGET".to_string() + } +} +``` + +#### 3. Register Command +```rust +// src/commands/mod.rs +pub mod new_command; + +// In CommandRegistry::new() +self.commands.insert("new-command".to_string(), Box::new(NewCommand)); +``` + +#### 4. Add to Main Dispatch +```rust +// src/main.rs +match cli.command { + Commands::NewCommand(args) => { + // Handle new command + } +} +``` + +### Adding New Features + +#### 1. Library Implementation +```rust +// src/lib/new_feature.rs +pub struct NewFeature { + // Feature implementation +} + +impl NewFeature { + pub fn new() -> Self { + // Constructor + } + + pub fn execute(&self) -> Result<(), Error> { + // Feature logic + } +} +``` + +#### 2. Integration +```rust +// src/lib/mod.rs +pub mod new_feature; + +// In main library struct +pub struct AptOstree { + // ... existing fields ... + new_feature: NewFeature, +} +``` + +#### 3. Testing +```rust +// tests/new_feature_tests.rs +#[test] +fn test_new_feature() { + let feature = NewFeature::new(); + assert!(feature.execute().is_ok()); +} +``` + +## Testing and Debugging + +### Unit Testing +```bash +# Run all tests +cargo test + +# Run specific test module +cargo test commands::package + +# Run tests with output +cargo test -- --nocapture + +# Run tests with specific feature +cargo test --features development +``` + +### Integration Testing +```bash +# Run integration tests +cargo test --test integration_tests + +# Run specific integration test +cargo test --test integration_tests test_package_installation +``` + +### Development Commands +```bash +# Run diagnostics +cargo run --features development -- internals diagnostics + +# Validate system state +cargo run --features development -- internals validate-state + +# Dump debug information +cargo run --features development -- internals debug-dump +``` + +### Debugging Tools + +#### Logging +```rust +use tracing::{info, warn, error, debug}; + +// Set log level +std::env::set_var("RUST_LOG", "debug"); + +// Use in code +debug!("Debug information"); +info!("Information message"); +warn!("Warning message"); +error!("Error message"); +``` + +#### Profiling +```bash +# Install profiling tools +cargo install flamegraph + +# Generate flamegraph +cargo flamegraph --bin apt-ostree -- install nginx + +# Memory profiling +cargo install cargo-valgrind +cargo valgrind test +``` + +### Code Quality Tools + +#### Clippy +```bash +# Run Clippy +cargo clippy + +# Run with specific rules +cargo clippy -- -D warnings -A clippy::too_many_arguments +``` + +#### Formatting +```bash +# Check formatting +cargo fmt -- --check + +# Format code +cargo fmt +``` + +#### Security Audit +```bash +# Check for vulnerabilities +cargo audit + +# Update dependencies +cargo update +``` + +## Contributing Guidelines + +### Code Style +- **Rust conventions**: Follow Rust style guide and idioms +- **Documentation**: Document all public APIs with doc comments +- **Error handling**: Use proper error types and Result handling +- **Testing**: Include tests for new functionality +- **Logging**: Use appropriate log levels for debugging + +### Pull Request Process +1. **Fork repository**: Create your own fork +2. **Create feature branch**: `git checkout -b feature/new-feature` +3. **Implement changes**: Follow coding guidelines +4. **Add tests**: Include unit and integration tests +5. **Update documentation**: Update relevant documentation +6. **Submit PR**: Create pull request with clear description + +### Commit Guidelines +``` +type(scope): description + +[optional body] + +[optional footer] +``` + +**Types**: feat, fix, docs, style, refactor, test, chore +**Scope**: cli, daemon, lib, commands, etc. + +### Review Process +- **Code review**: All changes require review +- **Testing**: Ensure all tests pass +- **Documentation**: Verify documentation is updated +- **Integration**: Test integration with existing features + +### Issue Reporting +When reporting issues, include: +- **Environment**: OS, version, dependencies +- **Steps to reproduce**: Clear reproduction steps +- **Expected behavior**: What should happen +- **Actual behavior**: What actually happens +- **Logs**: Relevant error logs and output + +## Advanced Development + +### Custom Builds +```bash +# Build with specific features +cargo build --features development,dev-full + +# Build for specific target +cargo build --target x86_64-unknown-linux-gnu + +# Cross-compilation +cargo build --target aarch64-unknown-linux-gnu +``` + +### Performance Optimization +```rust +// Use appropriate data structures +use std::collections::HashMap; // O(1) lookup +use std::collections::BTreeMap; // Ordered, O(log n) lookup + +// Avoid unnecessary allocations +let result = if condition { "value" } else { "default" }; +// Instead of +let result = if condition { "value".to_string() } else { "default".to_string() }; + +// Use iterators efficiently +let sum: u64 = items.iter().map(|x| x.value).sum(); +``` + +### Memory Management +```rust +// Use Arc for shared ownership +use std::sync::Arc; + +let shared_data = Arc::new(SharedData::new()); +let clone1 = Arc::clone(&shared_data); +let clone2 = Arc::clone(&shared_data); + +// Use Box for trait objects +let commands: Vec> = vec![ + Box::new(PackageCommand), + Box::new(SystemCommand), +]; +``` + +### Async Programming +```rust +use tokio::runtime::Runtime; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let result = async_operation().await?; + Ok(()) +} + +async fn async_operation() -> Result { + // Async implementation + Ok("result".to_string()) +} +``` + +## Troubleshooting Development Issues + +### Common Problems + +#### Build Failures +```bash +# Clean and rebuild +cargo clean +cargo build + +# Check Rust version +rustc --version +cargo --version + +# Update Rust toolchain +rustup update +``` + +#### Dependency Issues +```bash +# Check dependency tree +cargo tree + +# Update dependencies +cargo update + +# Check for conflicts +cargo check +``` + +#### Test Failures +```bash +# Run specific failing test +cargo test test_name -- --nocapture + +# Check test environment +cargo test --features development + +# Debug test setup +RUST_LOG=debug cargo test +``` + +### Getting Help +- **Documentation**: Check inline documentation and rustdoc +- **Issues**: Search existing GitHub issues +- **Discussions**: Use GitHub Discussions for questions +- **Community**: Join project community channels + +--- + +*This guide covers development aspects of apt-ostree. For user documentation, refer to the User Guide.* diff --git a/docs/development-commands-troubleshooting.md b/docs/development-commands-troubleshooting.md new file mode 100644 index 00000000..1ac50899 --- /dev/null +++ b/docs/development-commands-troubleshooting.md @@ -0,0 +1,645 @@ +# Development Commands Troubleshooting Guide + +## Overview +This document provides comprehensive troubleshooting information for apt-ostree development commands. It covers common issues, error messages, and solutions for the testutils, shlib-backend, and internals commands. + +## Table of Contents +1. [Common Issues](#common-issues) +2. [Error Messages and Solutions](#error-messages-and-solutions) +3. [Debugging Techniques](#debugging-techniques) +4. [Performance Issues](#performance-issues) +5. [Security Issues](#security-issues) +6. [System-Specific Problems](#system-specific-problems) + +## Common Issues + +### Command Not Found +**Problem**: Development commands are not available or return "command not found" + +**Symptoms**: +- `apt-ostree testutils --help` returns "unknown command" +- Development commands don't appear in help output + +**Causes**: +- Development features not compiled in +- Binary built without development features +- Feature flags not properly configured + +**Solutions**: +```bash +# 1. Verify development features are enabled +cargo build --features development + +# 2. Check if binary includes development commands +cargo run --features development -- testutils --help + +# 3. Rebuild with all development features +cargo build --features development,dev-full + +# 4. Verify feature compilation +cargo check --features development +``` + +**Prevention**: +- Always build with `--features development` for development work +- Use feature flags consistently across build environments +- Document required features in build scripts + +### Permission Denied +**Problem**: Commands fail with permission errors + +**Symptoms**: +- "Permission denied" errors +- "Operation not permitted" messages +- Commands fail even when run as root + +**Causes**: +- Insufficient user privileges +- Polkit policy restrictions +- File system permissions +- SELinux/AppArmor restrictions + +**Solutions**: +```bash +# 1. Check user privileges +whoami +groups $USER + +# 2. Verify Polkit policies +sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy + +# 3. Check file permissions +ls -la /usr/bin/apt-ostree +ls -la /var/lib/apt-ostree/ + +# 4. Verify daemon is running +sudo systemctl status apt-ostreed + +# 5. Check SELinux/AppArmor status +getenforce 2>/dev/null || echo "SELinux not available" +aa-status 2>/dev/null || echo "AppArmor not available" +``` + +**Prevention**: +- Ensure proper Polkit policies are installed +- Configure appropriate user groups and permissions +- Test commands in isolated environments first + +### Bubblewrap Issues +**Problem**: script-shell command fails with bubblewrap errors + +**Symptoms**: +- "bubblewrap: command not found" +- "Failed to execute bubblewrap" +- Containerization failures + +**Causes**: +- Bubblewrap not installed +- Insufficient bubblewrap permissions +- Kernel security restrictions +- User namespace limitations + +**Solutions**: +```bash +# 1. Check bubblewrap installation +which bubblewrap +bubblewrap --version + +# 2. Install bubblewrap if missing +sudo apt-get install bubblewrap + +# 3. Test bubblewrap functionality +bubblewrap --dev-bind / / --proc /proc -- echo "test" + +# 4. Check user namespace support +cat /proc/sys/kernel/unprivileged_userns_clone + +# 5. Verify kernel capabilities +capsh --print +``` + +**Prevention**: +- Ensure bubblewrap is available in build environment +- Test bubblewrap functionality before deployment +- Configure appropriate kernel parameters + +### OSTree Repository Issues +**Problem**: Commands fail due to OSTree repository problems + +**Symptoms**: +- "Repository not found" errors +- "Invalid repository" messages +- Commit resolution failures + +**Causes**: +- OSTree repository not initialized +- Repository corruption +- Permission issues +- Invalid repository path + +**Solutions**: +```bash +# 1. Check repository status +sudo ostree show --repo=/ostree/repo + +# 2. Verify repository integrity +sudo ostree fsck --repo=/ostree/repo + +# 3. Check repository permissions +ls -la /ostree/repo/ + +# 4. Reinitialize repository if needed +sudo ostree init --repo=/ostree/repo --mode=bare + +# 5. Check OSTree service status +sudo systemctl status ostree-remount +``` + +**Prevention**: +- Initialize OSTree repository during system setup +- Regular repository maintenance and integrity checks +- Proper backup and recovery procedures + +## Error Messages and Solutions + +### testutils Command Errors + +#### inject-pkglist Errors +**Error**: "Failed to open OSTree repository" +```bash +# Solution: Check repository path and permissions +sudo ostree show --repo=/ostree/repo +sudo chown -R root:root /ostree/repo +``` + +**Error**: "Invalid commit reference" +```bash +# Solution: Verify commit exists and is accessible +sudo ostree log --repo=/ostree/repo +sudo ostree show --repo=/ostree/repo +``` + +**Error**: "Failed to inject package list" +```bash +# Solution: Check metadata format and permissions +sudo ostree show --repo=/ostree/repo --print-metadata-key apt.packages +``` + +#### script-shell Errors +**Error**: "Failed to create bubblewrap container" +```bash +# Solution: Check bubblewrap installation and permissions +sudo apt-get install bubblewrap +sudo chmod +s /usr/bin/bubblewrap +``` + +**Error**: "Script execution failed" +```bash +# Solution: Verify script permissions and content +chmod +x /tmp/test.sh +cat /tmp/test.sh +``` + +**Error**: "Invalid root path" +```bash +# Solution: Check path exists and is accessible +ls -la /mnt/ostree/deploy/ +sudo mkdir -p /mnt/ostree/deploy/debian/13/amd64 +``` + +#### generate-synthetic-upgrade Errors +**Error**: "Failed to generate upgrade" +```bash +# Solution: Check system state and dependencies +sudo apt-ostree internals diagnostics +sudo apt-ostree status +``` + +**Error**: "Invalid package list" +```bash +# Solution: Verify package format and availability +apt-cache search +apt-cache show +``` + +### shlib-backend Command Errors + +#### get-basearch Errors +**Error**: "Failed to determine architecture" +```bash +# Solution: Check system architecture detection +dpkg --print-architecture +uname -m +arch +``` + +**Error**: "Invalid deployment reference" +```bash +# Solution: Verify deployment exists +sudo apt-ostree status +sudo ostree log --repo=/ostree/repo +``` + +#### varsubst-basearch Errors +**Error**: "Invalid variable format" +```bash +# Solution: Check variable syntax +echo "arch={{arch}}" | sudo apt-ostree shlib-backend varsubst-basearch +``` + +**Error**: "Variable substitution failed" +```bash +# Solution: Verify variable values and format +sudo apt-ostree shlib-backend get-basearch +``` + +#### packagelist-from-commit Errors +**Error**: "Commit not found" +```bash +# Solution: Verify commit exists +sudo ostree log --repo=/ostree/repo +sudo ostree show --repo=/ostree/repo +``` + +**Error**: "Failed to extract package list" +```bash +# Solution: Check commit metadata and permissions +sudo ostree show --repo=/ostree/repo --print-metadata +``` + +### internals Command Errors + +#### diagnostics Errors +**Error**: "Diagnostics failed" +```bash +# Solution: Check system state and permissions +sudo apt-ostree internals diagnostics --verbose +sudo systemctl status apt-ostreed +``` + +**Error**: "Component check failed" +```bash +# Solution: Check specific component status +sudo apt-ostree internals diagnostics --category ostree +sudo apt-ostree internals diagnostics --category apt +``` + +#### validate-state Errors +**Error**: "State validation failed" +```bash +# Solution: Check system consistency +sudo apt-ostree internals validate-state --verbose +sudo apt-ostree status +``` + +**Error**: "Component validation failed" +```bash +# Solution: Check specific component state +sudo apt-ostree internals validate-state --component ostree +sudo apt-ostree internals validate-state --component apt +``` + +#### debug-dump Errors +**Error**: "Failed to dump debug information" +```bash +# Solution: Check permissions and output location +sudo apt-ostree internals debug-dump --output /tmp/debug.json +ls -la /tmp/debug.json +``` + +**Error**: "Category dump failed" +```bash +# Solution: Check specific category availability +sudo apt-ostree internals debug-dump --category system-info +``` + +## Debugging Techniques + +### Verbose Output +```bash +# Enable verbose output for all commands +export APT_OSTREE_LOG_LEVEL=debug +export RUST_LOG=debug + +# Run commands with verbose flags +sudo apt-ostree testutils script-shell /tmp/test.sh --verbose +sudo apt-ostree internals diagnostics --verbose +``` + +### Log Analysis +```bash +# Check daemon logs +sudo journalctl -u apt-ostreed -f + +# Check system logs +sudo journalctl -f + +# Check specific log files +sudo tail -f /var/log/apt-ostreed.log +``` + +### Step-by-Step Debugging +```bash +# 1. Check basic functionality +sudo apt-ostree testutils moo + +# 2. Verify system state +sudo apt-ostree internals diagnostics + +# 3. Test specific components +sudo apt-ostree shlib-backend get-basearch + +# 4. Check dependencies +sudo apt-ostree internals validate-state + +# 5. Generate debug information +sudo apt-ostree internals debug-dump --output /tmp/debug.json +``` + +### Environment Variables +```bash +# Set debugging environment variables +export APT_OSTREE_DEBUG=1 +export APT_OSTREE_LOG_LEVEL=trace +export RUST_BACKTRACE=1 +export RUST_LOG=trace + +# Run commands with debugging +sudo -E apt-ostree testutils script-shell /tmp/test.sh +``` + +## Performance Issues + +### Slow Command Execution +**Problem**: Commands take too long to execute + +**Causes**: +- Large repository size +- Network latency +- Insufficient system resources +- Inefficient algorithms + +**Solutions**: +```bash +# 1. Check system resources +htop +free -h +df -h + +# 2. Monitor command performance +time sudo apt-ostree internals diagnostics + +# 3. Use profiling tools +cargo install flamegraph +cargo flamegraph --bin apt-ostree -- internals diagnostics + +# 4. Check repository size +du -sh /ostree/repo/ +sudo ostree summary --repo=/ostree/repo +``` + +**Optimization Techniques**: +- Use appropriate timeouts for long-running operations +- Implement caching for frequently accessed data +- Optimize database queries and file operations +- Use parallel processing where possible + +### Memory Issues +**Problem**: Commands consume excessive memory + +**Causes**: +- Memory leaks +- Large data structures +- Inefficient memory usage +- Insufficient system memory + +**Solutions**: +```bash +# 1. Monitor memory usage +ps aux | grep apt-ostree +cat /proc/$(pgrep apt-ostree)/status | grep VmRSS + +# 2. Check for memory leaks +valgrind --tool=memcheck --leak-check=full apt-ostree internals diagnostics + +# 3. Profile memory usage +cargo install cargo-valgrind +cargo valgrind test +``` + +**Optimization Techniques**: +- Use streaming for large data processing +- Implement proper cleanup and resource management +- Use appropriate data structures +- Monitor memory usage patterns + +## Security Issues + +### Authentication Failures +**Problem**: Commands fail due to authentication issues + +**Causes**: +- Invalid user credentials +- Expired authentication tokens +- Polkit policy restrictions +- D-Bus authentication failures + +**Solutions**: +```bash +# 1. Check user authentication +whoami +groups $USER + +# 2. Verify Polkit policies +sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy + +# 3. Check D-Bus authentication +dbus-send --system --dest=org.freedesktop.DBus --type=method_call --print-reply /org/freedesktop/DBus org.freedesktop.DBus.ListNames + +# 4. Test Polkit authentication +pkcheck --action-id org.projectatomic.aptostree1.manage --process $$ --user $USER +``` + +**Prevention**: +- Configure appropriate Polkit policies +- Use proper user authentication mechanisms +- Implement audit logging for security events +- Regular security policy reviews + +### Permission Escalation +**Problem**: Commands gain unexpected privileges + +**Causes**: +- Incorrect file permissions +- Insecure Polkit policies +- D-Bus interface vulnerabilities +- Container escape vulnerabilities + +**Solutions**: +```bash +# 1. Check file permissions +ls -la /usr/bin/apt-ostree +ls -la /var/lib/apt-ostree/ + +# 2. Verify Polkit policy security +sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy + +# 3. Check container isolation +bubblewrap --dev-bind / / --proc /proc -- id + +# 4. Audit privilege usage +sudo journalctl -u apt-ostreed | grep -i "privilege\|permission\|auth" +``` + +**Prevention**: +- Implement principle of least privilege +- Use secure containerization techniques +- Regular security audits and penetration testing +- Proper input validation and sanitization + +## System-Specific Problems + +### Debian/Ubuntu Issues +**Problem**: Commands fail on specific Debian/Ubuntu versions + +**Causes**: +- Version-specific dependencies +- Package compatibility issues +- System configuration differences +- Kernel version limitations + +**Solutions**: +```bash +# 1. Check system version +cat /etc/os-release +lsb_release -a + +# 2. Verify package compatibility +apt-cache policy apt-ostree +apt-cache policy libostree-1-1 + +# 3. Check kernel version +uname -r + +# 4. Verify system requirements +dpkg -l | grep -E "(ostree|apt|polkit)" +``` + +**Prevention**: +- Test on multiple system versions +- Document version-specific requirements +- Implement compatibility checks +- Use appropriate dependency versions + +### Architecture-Specific Issues +**Problem**: Commands fail on specific architectures + +**Causes**: +- Architecture-specific bugs +- Missing architecture support +- Binary compatibility issues +- Endianness problems + +**Solutions**: +```bash +# 1. Check system architecture +dpkg --print-architecture +uname -m +arch + +# 2. Verify binary compatibility +file /usr/bin/apt-ostree +ldd /usr/bin/apt-ostree + +# 3. Check architecture support +apt-ostree shlib-backend get-basearch + +# 4. Test cross-compilation +cargo build --target aarch64-unknown-linux-gnu +``` + +**Prevention**: +- Test on multiple architectures +- Implement architecture-specific code paths +- Use portable data formats +- Regular cross-architecture testing + +### Container/VM Issues +**Problem**: Commands fail in containerized or virtualized environments + +**Causes**: +- Limited system access +- Missing hardware support +- Resource limitations +- Isolation restrictions + +**Solutions**: +```bash +# 1. Check container environment +cat /proc/1/cgroup +systemd-detect-virt + +# 2. Verify system capabilities +capsh --print + +# 3. Check resource limits +ulimit -a +cat /proc/self/limits + +# 4. Test basic functionality +apt-ostree testutils moo +``` + +**Prevention**: +- Test in various container environments +- Implement graceful degradation +- Document environment requirements +- Use appropriate resource limits + +## Best Practices for Troubleshooting + +### Systematic Approach +1. **Identify the problem**: Understand what's failing and why +2. **Check system state**: Verify system health and configuration +3. **Test basic functionality**: Ensure core components work +4. **Isolate the issue**: Narrow down the problem scope +5. **Apply solutions**: Implement appropriate fixes +6. **Verify resolution**: Confirm the problem is solved +7. **Document solution**: Record the problem and solution + +### Logging and Monitoring +```bash +# Enable comprehensive logging +export APT_OSTREE_LOG_LEVEL=debug +export RUST_LOG=debug + +# Monitor system resources +htop +iotop +nethogs + +# Track command execution +time sudo apt-ostree internals diagnostics +``` + +### Testing and Validation +```bash +# Test in isolated environment +sudo apt-ostree testutils script-shell /tmp/test.sh --read-only + +# Validate system state +sudo apt-ostree internals validate-state + +# Run comprehensive diagnostics +sudo apt-ostree internals diagnostics --verbose +``` + +### Documentation and Knowledge Base +- **Record problems**: Document all issues and solutions +- **Build knowledge base**: Create troubleshooting guides +- **Share solutions**: Contribute to community knowledge +- **Regular updates**: Keep documentation current + +--- + +*This guide covers troubleshooting for apt-ostree development commands. For general troubleshooting, refer to the main User Guide.* diff --git a/docs/development-commands-usage.md b/docs/development-commands-usage.md new file mode 100644 index 00000000..5afa5838 --- /dev/null +++ b/docs/development-commands-usage.md @@ -0,0 +1,509 @@ +# 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.* diff --git a/docs/development-workflow.md b/docs/development-workflow.md new file mode 100644 index 00000000..42dc98ec --- /dev/null +++ b/docs/development-workflow.md @@ -0,0 +1,523 @@ +# Development Workflow Documentation + +## Overview +This document describes the development workflow for apt-ostree, including setup, testing, debugging, and contribution guidelines. It provides developers with a comprehensive guide to working with the codebase. + +## Table of Contents +1. [Development Environment Setup](#development-environment-setup) +2. [Development Workflow](#development-workflow) +3. [Testing Procedures](#testing-procedures) +4. [Debugging Techniques](#debugging-techniques) +5. [Code Quality and Standards](#code-quality-and-standards) +6. [Contribution Guidelines](#contribution-guidelines) +7. [Release Process](#release-process) + +## Development Environment Setup + +### Prerequisites +- **Rust toolchain**: Rust 1.75+ with Cargo +- **System dependencies**: See installation guide +- **Development tools**: Git, make, pkg-config +- **Documentation tools**: rustdoc, cargo-doc + +### Initial Setup +```bash +# Clone repository +git clone https://github.com/robojerk/apt-ostree.git +cd apt-ostree + +# Install Rust toolchain +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +source ~/.cargo/env + +# Install system dependencies +sudo apt-get install build-essential pkg-config \ + libostree-dev libapt-pkg-dev libpolkit-gobject-1-dev \ + libdbus-1-dev libsystemd-dev + +# Install development tools +cargo install cargo-outdated cargo-audit cargo-tarpaulin +``` + +### Environment Configuration +```bash +# Set development environment variables +export APT_OSTREE_DEV_MODE=1 +export APT_OSTREE_LOG_LEVEL=debug +export RUST_LOG=debug + +# Add to ~/.bashrc or ~/.zshrc +echo 'export APT_OSTREE_DEV_MODE=1' >> ~/.bashrc +echo 'export APT_OSTREE_LOG_LEVEL=debug' >> ~/.bashrc +echo 'export RUST_LOG=debug' >> ~/.bashrc +``` + +### IDE Configuration +#### VS Code +```json +// .vscode/settings.json +{ + "rust-analyzer.checkOnSave.command": "clippy", + "rust-analyzer.cargo.features": ["development"], + "rust-analyzer.procMacro.enable": true, + "rust-analyzer.cargo.buildScripts.enable": true +} +``` + +#### IntelliJ IDEA / CLion +- Install Rust plugin +- Configure Rust toolchain +- Enable Cargo features: `development,dev-full` + +## Development Workflow + +### Daily Development Cycle +```bash +# 1. Start development session +git pull origin main +cargo check --features development + +# 2. Make changes and test +cargo build --features development +cargo test --features development + +# 3. Commit changes +git add . +git commit -m "feat(commands): add new feature X" + +# 4. Push changes +git push origin feature-branch +``` + +### Feature Development Workflow +```bash +# 1. Create feature branch +git checkout -b feature/new-feature + +# 2. Implement feature +# ... make changes ... + +# 3. Add tests +# ... add test cases ... + +# 4. Update documentation +# ... update docs ... + +# 5. Test thoroughly +cargo test --features development +cargo clippy --features development + +# 6. Create pull request +git push origin feature/new-feature +# Create PR on GitHub +``` + +### Bug Fix Workflow +```bash +# 1. Create bug fix branch +git checkout -b fix/bug-description + +# 2. Reproduce bug +# ... reproduce issue ... + +# 3. Fix bug +# ... implement fix ... + +# 4. Add regression test +# ... add test case ... + +# 5. Test fix +cargo test --features development + +# 6. Create pull request +git push origin fix/bug-description +``` + +## Testing Procedures + +### Unit Testing +```bash +# Run all unit tests +cargo test + +# Run specific test module +cargo test commands::package + +# Run tests with output +cargo test -- --nocapture + +# Run tests with specific feature +cargo test --features development + +# Run tests in parallel +cargo test -- --test-threads 4 +``` + +### Integration Testing +```bash +# Run integration tests +cargo test --test integration_tests + +# Run specific integration test +cargo test --test integration_tests test_package_installation + +# Run integration tests with verbose output +cargo test --test integration_tests -- --nocapture +``` + +### Development Commands Testing +```bash +# Test development commands +cargo run --features development -- testutils --help +cargo run --features development -- shlib-backend --help +cargo run --features development -- internals --help + +# Test specific development command +cargo run --features development -- testutils moo +cargo run --features development -- shlib-backend get-basearch +cargo run --features development -- internals diagnostics +``` + +### Performance Testing +```bash +# Install performance testing tools +cargo install cargo-bench + +# Run benchmarks +cargo bench + +# Profile performance +cargo install flamegraph +cargo flamegraph --bin apt-ostree -- internals diagnostics + +# Memory profiling +cargo install cargo-valgrind +cargo valgrind test +``` + +### Security Testing +```bash +# Run security audit +cargo audit + +# Check for known vulnerabilities +cargo audit --deny warnings + +# Dependency vulnerability scan +cargo install cargo-audit +cargo audit +``` + +## Debugging Techniques + +### Logging and Tracing +```rust +use tracing::{info, warn, error, debug, trace}; + +// Set log level +std::env::set_var("RUST_LOG", "debug"); + +// Use in code +debug!("Debug information: {:?}", data); +info!("Information message: {}", message); +warn!("Warning message: {}", warning); +error!("Error message: {}", error); +trace!("Trace information: {:?}", trace_data); +``` + +### Interactive Debugging +```bash +# Run with debugger +rust-gdb --args target/debug/apt-ostree internals diagnostics + +# Use println! for quick debugging +cargo run --features development -- internals diagnostics + +# Enable backtrace +export RUST_BACKTRACE=1 +cargo run --features development -- internals diagnostics +``` + +### Development Commands for Debugging +```bash +# Run system diagnostics +sudo apt-ostree internals diagnostics --verbose + +# Validate system state +sudo apt-ostree internals validate-state --strict-mode + +# Dump debug information +sudo apt-ostree internals debug-dump --output /tmp/debug.json + +# Test basic functionality +sudo apt-ostree testutils moo + +# Execute debug script +sudo apt-ostree testutils script-shell /tmp/debug.sh --verbose +``` + +### Profiling and Analysis +```bash +# CPU profiling +cargo install cargo-flamegraph +cargo flamegraph --bin apt-ostree -- internals diagnostics + +# Memory profiling +cargo install cargo-valgrind +cargo valgrind test + +# Code coverage +cargo install cargo-tarpaulin +cargo tarpaulin --out Html --output-dir coverage +``` + +## Code Quality and Standards + +### Code Style +- **Rust conventions**: Follow Rust style guide and idioms +- **Formatting**: Use `cargo fmt` for consistent formatting +- **Documentation**: Document all public APIs with doc comments +- **Error handling**: Use proper error types and Result handling + +### Linting and Analysis +```bash +# Run Clippy +cargo clippy --features development + +# Run with specific rules +cargo clippy --features development -- -D warnings + +# Allow specific warnings +cargo clippy --features development -- -D warnings -A clippy::too_many_arguments + +# Check formatting +cargo fmt -- --check + +# Format code +cargo fmt +``` + +### Documentation Standards +```rust +/// Brief description of the function +/// +/// Detailed description with examples and usage notes. +/// +/// # Arguments +/// * `param1` - Description of first parameter +/// * `param2` - Description of second parameter +/// +/// # Returns +/// Result containing success value or error +/// +/// # Examples +/// ``` +/// use apt_ostree::lib::example::Example; +/// +/// let result = Example::new().do_something(); +/// assert!(result.is_ok()); +/// ``` +/// +/// # Errors +/// Returns error if operation fails +pub fn example_function(param1: String, param2: u32) -> Result<(), Error> { + // Implementation +} +``` + +### Testing Standards +```rust +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_function_name() { + // Arrange + let input = "test"; + + // Act + let result = function(input); + + // Assert + assert!(result.is_ok()); + assert_eq!(result.unwrap(), "expected"); + } + + #[test] + #[should_panic(expected = "error message")] + fn test_function_panics() { + function("invalid"); + } + + #[test] + fn test_function_with_result() -> Result<(), Box> { + let result = function("test")?; + assert_eq!(result, "expected"); + Ok(()) + } +} +``` + +## Contribution Guidelines + +### Pull Request Process +1. **Fork repository**: Create your own fork +2. **Create feature branch**: `git checkout -b feature/new-feature` +3. **Implement changes**: Follow coding guidelines +4. **Add tests**: Include unit and integration tests +5. **Update documentation**: Update relevant documentation +6. **Submit PR**: Create pull request with clear description + +### Commit Guidelines +``` +type(scope): description + +[optional body] + +[optional footer] +``` + +**Types**: feat, fix, docs, style, refactor, test, chore +**Scope**: cli, daemon, lib, commands, etc. + +**Examples**: +``` +feat(commands): add new package management command + +fix(daemon): resolve memory leak in transaction handling + +docs(user-guide): update installation instructions + +test(integration): add end-to-end package installation test +``` + +### Review Process +- **Code review**: All changes require review +- **Testing**: Ensure all tests pass +- **Documentation**: Verify documentation is updated +- **Integration**: Test integration with existing features + +### Issue Reporting +When reporting issues, include: +- **Environment**: OS, version, dependencies +- **Steps to reproduce**: Clear reproduction steps +- **Expected behavior**: What should happen +- **Actual behavior**: What actually happens +- **Logs**: Relevant error logs and output + +## Release Process + +### Pre-Release Checklist +```bash +# 1. Update version numbers +# Update Cargo.toml, debian/changelog, etc. + +# 2. Run full test suite +cargo test --features development +cargo test --test integration_tests + +# 3. Run code quality checks +cargo clippy --features development -- -D warnings +cargo fmt -- --check +cargo audit + +# 4. Build all targets +cargo build --release --features development +cargo build --release --features dev-full + +# 5. Test development commands +cargo run --features development -- testutils --help +cargo run --features development -- shlib-backend --help +cargo run --features development -- internals --help + +# 6. Build documentation +cargo doc --features development --no-deps + +# 7. Build Debian package +./build-debian-trixie.sh +``` + +### Release Steps +```bash +# 1. Create release branch +git checkout -b release/v0.2.0 + +# 2. Update version numbers +# ... update version files ... + +# 3. Run final tests +cargo test --features development +cargo test --test integration_tests + +# 4. Commit version changes +git add . +git commit -m "chore(release): bump version to 0.2.0" + +# 5. Tag release +git tag -a v0.2.0 -m "Release version 0.2.0" + +# 6. Push release +git push origin release/v0.2.0 +git push origin v0.2.0 + +# 7. Create GitHub release +# ... create release on GitHub ... + +# 8. Merge to main +git checkout main +git merge release/v0.2.0 +git push origin main +``` + +### Post-Release Tasks +```bash +# 1. Update documentation +# ... update version references ... + +# 2. Announce release +# ... announce on mailing lists, forums, etc. ... + +# 3. Monitor for issues +# ... watch for bug reports and issues ... + +# 4. Plan next release +# ... plan features for next version ... +``` + +## Development Best Practices + +### Code Organization +- **Modular design**: Keep modules focused and cohesive +- **Separation of concerns**: Separate logic from presentation +- **Dependency management**: Minimize dependencies and avoid circular references +- **Error handling**: Use consistent error types and handling patterns + +### Performance Considerations +- **Efficient algorithms**: Use appropriate algorithms and data structures +- **Memory management**: Avoid unnecessary allocations and memory leaks +- **Async operations**: Use async/await for I/O operations +- **Caching**: Implement caching for expensive operations + +### Security Considerations +- **Input validation**: Validate all user inputs +- **Authentication**: Implement proper authentication and authorization +- **Resource limits**: Set appropriate limits for operations +- **Audit logging**: Log security-relevant events + +### Testing Strategy +- **Unit tests**: Test individual functions and methods +- **Integration tests**: Test component interactions +- **End-to-end tests**: Test complete workflows +- **Performance tests**: Test performance characteristics +- **Security tests**: Test security aspects + +### Documentation Strategy +- **API documentation**: Document all public APIs +- **User guides**: Provide comprehensive user documentation +- **Developer guides**: Document development processes +- **Examples**: Provide working examples for common use cases + +--- + +*This guide covers the development workflow for apt-ostree. For user documentation, refer to the User Guide.* diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 00000000..14a39951 --- /dev/null +++ b/docs/user-guide.md @@ -0,0 +1,427 @@ +# apt-ostree User Guide + +## System Requirements + +### Supported Operating Systems +- Debian 13+ (Trixie) or newer +- Ubuntu 25.04+ (Noble Numbat) or newer + +### Required System Components +- OSTree 2025.2+ +- APT 3.0+ +- Systemd 255+ +- Polkit 123+ + +## Table of Contents +1. [Installation](#installation) +2. [Basic Setup](#basic-setup) +3. [Basic Operations](#basic-operations) +4. [Advanced Features](#advanced-features) +5. [Troubleshooting](#troubleshooting) +6. [Migration Guide](#migration-guide) + +## Installation + +### Prerequisites +apt-ostree requires the following system components: +- Debian 13+ or Ubuntu 24.04+ +- OSTree 2025.2+ +- APT 3.0+ +- systemd +- Polkit +- D-Bus + +### Installing from Debian Package +```bash +# Download and install the package +sudo dpkg -i apt-ostree_0.1.0-2_amd64.deb + +# Install dependencies if needed +sudo apt-get install -f +``` + +### Installing from Source +```bash +# Clone the repository +git clone https://github.com/robojerk/apt-ostree.git +cd apt-ostree + +# Install build dependencies +sudo apt-get install build-essential cargo rustc pkg-config \ + libostree-dev libapt-pkg-dev libpolkit-gobject-1-dev \ + libdbus-1-dev libsystemd-dev + +# Build and install +cargo build --release +sudo install -m 755 target/release/apt-ostree /usr/local/bin/ +sudo install -m 755 target/release/apt-ostreed /usr/local/libexec/ +``` + +## Basic Setup + +### Initial Configuration +1. **Create configuration directory:** + ```bash + sudo mkdir -p /etc/apt-ostree + ``` + +2. **Create configuration file:** + ```bash + sudo tee /etc/apt-ostree/config.toml > /dev/null <